@suss/ir-core 0.13.2 → 0.14.0

package/dist/{chunk-AQYS5AC6.js → chunk-HSJYPBJU.js}

@@ -309,6 +309,20 @@ var metricSemantics = defineBoundarySemantics({
 
 // src/semantics/rest.ts
 import { z as z6 } from "zod";
+
+// src/urlPath.ts
+var SCHEME_ORIGIN = /^[a-zA-Z][a-zA-Z\d+.-]*:\/\/[^/]*/;
+var PROTOCOL_RELATIVE_ORIGIN = /^\/\/[^/]*/;
+function pathAfterOrigin(text) {
+  const withoutOrigin = text.replace(SCHEME_ORIGIN, "").replace(PROTOCOL_RELATIVE_ORIGIN, "");
+  const cut = withoutOrigin.search(/[?#]/);
+  return cut === -1 ? withoutOrigin : withoutOrigin.slice(0, cut);
+}
+function statesAnOrigin(text) {
+  return SCHEME_ORIGIN.test(text) || PROTOCOL_RELATIVE_ORIGIN.test(text);
+}
+
+// src/semantics/rest.ts
 var RestSemanticsSchema = z6.object({
   name: z6.literal("rest"),
   /**
@@ -327,6 +341,11 @@ var RestSemanticsSchema = z6.object({
    */
   declaredResponses: z6.array(z6.number()).optional()
 });
+var OPENING_HOLE = /^\{([^{}]+)\}(.*)$/;
+function variableOf(label) {
+  const parts = label.split(".");
+  return parts[parts.length - 1] ?? label;
+}
 function normalizePath(path) {
   let normalized = path.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
   if (normalized.length > 1 && normalized.endsWith("/")) {
@@ -436,6 +455,37 @@ var restSemantics = defineBoundarySemantics({
       }
       return routePathAdmits(semantics.path, path) ? "match" : "nomatch";
     },
+    /**
+     * A call whose base URL the deployment fills in, resolved to the
+     * path it reaches.
+     *
+     * The source cannot settle this on its own, which is why the
+     * adapter leaves the hole in. `API_BASE` could be
+     * `http://backend.internal`, and then the path is `/orders`. It
+     * could equally be `/api/v2`, and then the path is
+     * `/api/v2/orders`. Putting the deployed value in and reading the
+     * path back out gets the right one either way.
+     *
+     * Only a hole at the front is a base URL. A hole further along is a
+     * route parameter, and `/orders/{id}` means every id rather than a
+     * variable somebody set.
+     */
+    groundName(semantics, deployedAs) {
+      if (semantics.path === null) {
+        return null;
+      }
+      const opening = OPENING_HOLE.exec(semantics.path);
+      if (opening === null) {
+        return null;
+      }
+      const [, label, rest] = opening;
+      const base = deployedAs(variableOf(label));
+      if (base === null) {
+        return null;
+      }
+      const grounded = pathAfterOrigin(`${base}${rest}`);
+      return { ...semantics, path: grounded === "" ? "/" : grounded };
+    },
     ruleBoundary: {
       // "METHOD /path": one leading token, then an absolute path.
       claims(raw) {
@@ -718,6 +768,8 @@ export {
   channelsPair,
   MessageBusSemanticsSchema,
   MetricSemanticsSchema,
+  pathAfterOrigin,
+  statesAnOrigin,
   RestSemanticsSchema,
   normalizePath,
   pathShape,

package/dist/index.cjs

@@ -62,6 +62,7 @@ __export(index_exports, {
   gqlIdentityKey: () => gqlIdentityKey,
   graphqlOperationBinding: () => graphqlOperationBinding,
   graphqlResolverBinding: () => graphqlResolverBinding,
+  groundedPairingKey: () => groundedPairingKey,
   hasNameHole: () => hasNameHole,
   isGraphqlOperationBinding: () => isGraphqlOperationBinding,
   messageBusBinding: () => messageBusBinding,
@@ -78,6 +79,7 @@ __export(index_exports, {
   pairingKey: () => pairingKey,
   parseBoundaryName: () => parseBoundaryName,
   parseChannel: () => parseChannel,
+  pathAfterOrigin: () => pathAfterOrigin,
   pathShape: () => pathShape,
   patternHole: () => patternHole,
   referenceFromName: () => referenceFromName,
@@ -91,6 +93,7 @@ __export(index_exports, {
   semanticsAgree: () => semanticsAgree,
   semconvAttributes: () => semconvAttributes,
   servesRequest: () => servesRequest,
+  statesAnOrigin: () => statesAnOrigin,
   storageBinding: () => storageBinding,
   typeDefinitionKey: () => typeDefinitionKey,
   validateRule: () => validateRule,
@@ -409,6 +412,20 @@ var metricSemantics = defineBoundarySemantics({
 
 // src/semantics/rest.ts
 var import_zod6 = require("zod");
+
+// src/urlPath.ts
+var SCHEME_ORIGIN = /^[a-zA-Z][a-zA-Z\d+.-]*:\/\/[^/]*/;
+var PROTOCOL_RELATIVE_ORIGIN = /^\/\/[^/]*/;
+function pathAfterOrigin(text) {
+  const withoutOrigin = text.replace(SCHEME_ORIGIN, "").replace(PROTOCOL_RELATIVE_ORIGIN, "");
+  const cut = withoutOrigin.search(/[?#]/);
+  return cut === -1 ? withoutOrigin : withoutOrigin.slice(0, cut);
+}
+function statesAnOrigin(text) {
+  return SCHEME_ORIGIN.test(text) || PROTOCOL_RELATIVE_ORIGIN.test(text);
+}
+
+// src/semantics/rest.ts
 var RestSemanticsSchema = import_zod6.z.object({
   name: import_zod6.z.literal("rest"),
   /**
@@ -427,6 +444,11 @@ var RestSemanticsSchema = import_zod6.z.object({
    */
   declaredResponses: import_zod6.z.array(import_zod6.z.number()).optional()
 });
+var OPENING_HOLE = /^\{([^{}]+)\}(.*)$/;
+function variableOf(label) {
+  const parts = label.split(".");
+  return parts[parts.length - 1] ?? label;
+}
 function normalizePath(path) {
   let normalized = path.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
   if (normalized.length > 1 && normalized.endsWith("/")) {
@@ -536,6 +558,37 @@ var restSemantics = defineBoundarySemantics({
       }
       return routePathAdmits(semantics.path, path) ? "match" : "nomatch";
     },
+    /**
+     * A call whose base URL the deployment fills in, resolved to the
+     * path it reaches.
+     *
+     * The source cannot settle this on its own, which is why the
+     * adapter leaves the hole in. `API_BASE` could be
+     * `http://backend.internal`, and then the path is `/orders`. It
+     * could equally be `/api/v2`, and then the path is
+     * `/api/v2/orders`. Putting the deployed value in and reading the
+     * path back out gets the right one either way.
+     *
+     * Only a hole at the front is a base URL. A hole further along is a
+     * route parameter, and `/orders/{id}` means every id rather than a
+     * variable somebody set.
+     */
+    groundName(semantics, deployedAs) {
+      if (semantics.path === null) {
+        return null;
+      }
+      const opening = OPENING_HOLE.exec(semantics.path);
+      if (opening === null) {
+        return null;
+      }
+      const [, label, rest] = opening;
+      const base = deployedAs(variableOf(label));
+      if (base === null) {
+        return null;
+      }
+      const grounded = pathAfterOrigin(`${base}${rest}`);
+      return { ...semantics, path: grounded === "" ? "/" : grounded };
+    },
     ruleBoundary: {
       // "METHOD /path": one leading token, then an absolute path.
       claims(raw) {
@@ -827,6 +880,13 @@ function semconvAttributes(binding) {
 function boundaryKey(binding) {
   return behaviorOf(binding.semantics).identityKey(binding.semantics);
 }
+function groundedPairingKey(binding, deployedAs) {
+  const behavior = behaviorOf(binding.semantics);
+  const grounded = behavior.groundName?.(binding.semantics, deployedAs) ?? null;
+  return pairingKey(
+    grounded === null ? binding : { ...binding, semantics: grounded }
+  );
+}
 function pairingKey(binding) {
   const behavior = behaviorOf(binding.semantics);
   return (behavior.pairingKey ?? behavior.identityKey)(binding.semantics);
@@ -1442,6 +1502,7 @@ function metricBinding(opts) {
   gqlIdentityKey,
   graphqlOperationBinding,
   graphqlResolverBinding,
+  groundedPairingKey,
   hasNameHole,
   isGraphqlOperationBinding,
   messageBusBinding,
@@ -1458,6 +1519,7 @@ function metricBinding(opts) {
   pairingKey,
   parseBoundaryName,
   parseChannel,
+  pathAfterOrigin,
   pathShape,
   patternHole,
   referenceFromName,
@@ -1471,6 +1533,7 @@ function metricBinding(opts) {
   semanticsAgree,
   semconvAttributes,
   servesRequest,
+  statesAnOrigin,
   storageBinding,
   typeDefinitionKey,
   validateRule,

package/dist/index.d.cts

@@ -117,6 +117,24 @@ interface BoundaryBehavior<S extends {
      * does not apply, and unknown means this declaration cannot settle it.
      */
     servesRequest?(semantics: S, method: string, path: string): MatchResult;
+    /**
+     * The same boundary with a name the deployment fills in put in.
+     *
+     * A call written as `fetch(`${process.env.API_BASE}/orders`)` gets
+     * part of its boundary from the source and part from whatever runs
+     * the code. Both parts have to be in before anybody can see that the
+     * two sides describe one boundary.
+     *
+     * `deployedAs` is already scoped to the unit this boundary belongs to.
+     * A protocol asks for a variable and gets back what this deployment
+     * sets it to, or null. Return null to leave the boundary as it is,
+     * which is right whenever nothing needs filling in or nothing can
+     * fill it.
+     *
+     * A protocol whose names are settled in the source leaves this
+     * undefined.
+     */
+    groundName?(semantics: S, deployedAs: (variable: string) => string | null): S | null;
     /**
      * Whether a provider produces a status and a body that a consumer
      * reads back. Every protocol has to state this, so that one added
@@ -219,6 +237,16 @@ declare function semconvAttributes(binding: BoundaryBinding): Record<string, str
  */
 
 declare function boundaryKey(binding: BoundaryBinding): string | null;
+/**
+ * The bucket a boundary pairs in, with any name the deployment fills in
+ * put in first.
+ *
+ * A consumer that gets its base URL from the runtime states a different
+ * string from the provider it reaches, and the two are one boundary.
+ * Every protocol that has such a name says how to fill it in, and one
+ * whose names are settled in the source keys exactly as before.
+ */
+declare function groundedPairingKey(binding: BoundaryBinding, deployedAs: (variable: string) => string | null): string | null;
 declare function pairingKey(binding: BoundaryBinding): string | null;
 declare function semanticsAgree(a: Semantics, b: Semantics): boolean;
 declare function boundaryLabel(binding: BoundaryBinding): string | null;
@@ -554,6 +582,30 @@ declare function applySuppressionsToFindings<T extends SuppressibleFinding>(find
  */
 declare function countsForThreshold(finding: SuppressibleFinding): boolean;
 
+/**
+ * urlPath.ts: the path part of a URL, however the URL was written.
+ *
+ * Two sides of one boundary spell it differently. A provider says
+ * `/orders`, because a route is mounted at a path. A consumer says
+ * `http://backend.internal/orders`, because a call has to say which
+ * host. They are the same boundary, and pairing them means reading the
+ * path out of both.
+ *
+ * The query and the fragment come off with the origin. Neither picks a
+ * route: `/orders?page=2` reaches the same handler as `/orders`.
+ */
+/**
+ * The path a URL states, with any origin, query, and fragment removed.
+ *
+ * Text that states no origin comes back with only the query and the
+ * fragment removed, since a relative URL is already a path. A URL that
+ * is nothing but an origin comes back as an empty string, which is what
+ * a caller wanting a path should treat as "the root".
+ */
+declare function pathAfterOrigin(text: string): string;
+/** Whether the text opens with an origin rather than with a path. */
+declare function statesAnOrigin(text: string): boolean;
+
 /**
  * @suss/ir-core: primitives shared across suss IRs.
  *
@@ -684,4 +736,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 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 };
+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, groundedPairingKey, hasNameHole, isGraphqlOperationBinding, messageBusBinding, metricBinding, metricIdentityKey, namePatternFromSub, namePatternKey, namesAgree, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseBoundaryName, parseChannel, pathAfterOrigin, patternHole, referenceFromName, referenceName, referenceOf, reportsUnpairedItself, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, semconvAttributes, servesRequest, statesAnOrigin, storageBinding, validateRule };

package/dist/index.d.ts

@@ -117,6 +117,24 @@ interface BoundaryBehavior<S extends {
      * does not apply, and unknown means this declaration cannot settle it.
      */
     servesRequest?(semantics: S, method: string, path: string): MatchResult;
+    /**
+     * The same boundary with a name the deployment fills in put in.
+     *
+     * A call written as `fetch(`${process.env.API_BASE}/orders`)` gets
+     * part of its boundary from the source and part from whatever runs
+     * the code. Both parts have to be in before anybody can see that the
+     * two sides describe one boundary.
+     *
+     * `deployedAs` is already scoped to the unit this boundary belongs to.
+     * A protocol asks for a variable and gets back what this deployment
+     * sets it to, or null. Return null to leave the boundary as it is,
+     * which is right whenever nothing needs filling in or nothing can
+     * fill it.
+     *
+     * A protocol whose names are settled in the source leaves this
+     * undefined.
+     */
+    groundName?(semantics: S, deployedAs: (variable: string) => string | null): S | null;
     /**
      * Whether a provider produces a status and a body that a consumer
      * reads back. Every protocol has to state this, so that one added
@@ -219,6 +237,16 @@ declare function semconvAttributes(binding: BoundaryBinding): Record<string, str
  */
 
 declare function boundaryKey(binding: BoundaryBinding): string | null;
+/**
+ * The bucket a boundary pairs in, with any name the deployment fills in
+ * put in first.
+ *
+ * A consumer that gets its base URL from the runtime states a different
+ * string from the provider it reaches, and the two are one boundary.
+ * Every protocol that has such a name says how to fill it in, and one
+ * whose names are settled in the source keys exactly as before.
+ */
+declare function groundedPairingKey(binding: BoundaryBinding, deployedAs: (variable: string) => string | null): string | null;
 declare function pairingKey(binding: BoundaryBinding): string | null;
 declare function semanticsAgree(a: Semantics, b: Semantics): boolean;
 declare function boundaryLabel(binding: BoundaryBinding): string | null;
@@ -554,6 +582,30 @@ declare function applySuppressionsToFindings<T extends SuppressibleFinding>(find
  */
 declare function countsForThreshold(finding: SuppressibleFinding): boolean;
 
+/**
+ * urlPath.ts: the path part of a URL, however the URL was written.
+ *
+ * Two sides of one boundary spell it differently. A provider says
+ * `/orders`, because a route is mounted at a path. A consumer says
+ * `http://backend.internal/orders`, because a call has to say which
+ * host. They are the same boundary, and pairing them means reading the
+ * path out of both.
+ *
+ * The query and the fragment come off with the origin. Neither picks a
+ * route: `/orders?page=2` reaches the same handler as `/orders`.
+ */
+/**
+ * The path a URL states, with any origin, query, and fragment removed.
+ *
+ * Text that states no origin comes back with only the query and the
+ * fragment removed, since a relative URL is already a path. A URL that
+ * is nothing but an origin comes back as an empty string, which is what
+ * a caller wanting a path should treat as "the root".
+ */
+declare function pathAfterOrigin(text: string): string;
+/** Whether the text opens with an origin rather than with a path. */
+declare function statesAnOrigin(text: string): boolean;
+
 /**
  * @suss/ir-core: primitives shared across suss IRs.
  *
@@ -684,4 +736,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 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 };
+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, groundedPairingKey, hasNameHole, isGraphqlOperationBinding, messageBusBinding, metricBinding, metricIdentityKey, namePatternFromSub, namePatternKey, namesAgree, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseBoundaryName, parseChannel, pathAfterOrigin, patternHole, referenceFromName, referenceName, referenceOf, reportsUnpairedItself, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, semconvAttributes, servesRequest, statesAnOrigin, storageBinding, validateRule };

package/dist/index.js

@@ -29,12 +29,14 @@ import {
   metricIdentityKey,
   normalizePath,
   parseChannel,
+  pathAfterOrigin,
   pathShape,
   routePathAdmits,
   semconvMappingOf,
+  statesAnOrigin,
   typeDefinitionKey,
   withDefinitionsInlined
-} from "./chunk-AQYS5AC6.js";
+} from "./chunk-HSJYPBJU.js";
 
 // src/semconv.ts
 function semconvAttributes(binding) {
@@ -59,6 +61,13 @@ function semconvAttributes(binding) {
 function boundaryKey(binding) {
   return behaviorOf(binding.semantics).identityKey(binding.semantics);
 }
+function groundedPairingKey(binding, deployedAs) {
+  const behavior = behaviorOf(binding.semantics);
+  const grounded = behavior.groundName?.(binding.semantics, deployedAs) ?? null;
+  return pairingKey(
+    grounded === null ? binding : { ...binding, semantics: grounded }
+  );
+}
 function pairingKey(binding) {
   const behavior = behaviorOf(binding.semantics);
   return (behavior.pairingKey ?? behavior.identityKey)(binding.semantics);
@@ -673,6 +682,7 @@ export {
   gqlIdentityKey,
   graphqlOperationBinding,
   graphqlResolverBinding,
+  groundedPairingKey,
   hasNameHole,
   isGraphqlOperationBinding,
   messageBusBinding,
@@ -689,6 +699,7 @@ export {
   pairingKey,
   parseBoundaryName,
   parseChannel,
+  pathAfterOrigin,
   pathShape,
   patternHole,
   referenceFromName,
@@ -702,6 +713,7 @@ export {
   semanticsAgree,
   semconvAttributes,
   servesRequest,
+  statesAnOrigin,
   storageBinding,
   typeDefinitionKey,
   validateRule,

package/dist/schemas.cjs

@@ -344,6 +344,17 @@ var metricSemantics = defineBoundarySemantics({
 
 // src/semantics/rest.ts
 var import_zod6 = require("zod");
+
+// src/urlPath.ts
+var SCHEME_ORIGIN = /^[a-zA-Z][a-zA-Z\d+.-]*:\/\/[^/]*/;
+var PROTOCOL_RELATIVE_ORIGIN = /^\/\/[^/]*/;
+function pathAfterOrigin(text) {
+  const withoutOrigin = text.replace(SCHEME_ORIGIN, "").replace(PROTOCOL_RELATIVE_ORIGIN, "");
+  const cut = withoutOrigin.search(/[?#]/);
+  return cut === -1 ? withoutOrigin : withoutOrigin.slice(0, cut);
+}
+
+// src/semantics/rest.ts
 var RestSemanticsSchema = import_zod6.z.object({
   name: import_zod6.z.literal("rest"),
   /**
@@ -362,6 +373,11 @@ var RestSemanticsSchema = import_zod6.z.object({
    */
   declaredResponses: import_zod6.z.array(import_zod6.z.number()).optional()
 });
+var OPENING_HOLE = /^\{([^{}]+)\}(.*)$/;
+function variableOf(label) {
+  const parts = label.split(".");
+  return parts[parts.length - 1] ?? label;
+}
 function normalizePath(path) {
   let normalized = path.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
   if (normalized.length > 1 && normalized.endsWith("/")) {
@@ -471,6 +487,37 @@ var restSemantics = defineBoundarySemantics({
       }
       return routePathAdmits(semantics.path, path) ? "match" : "nomatch";
     },
+    /**
+     * A call whose base URL the deployment fills in, resolved to the
+     * path it reaches.
+     *
+     * The source cannot settle this on its own, which is why the
+     * adapter leaves the hole in. `API_BASE` could be
+     * `http://backend.internal`, and then the path is `/orders`. It
+     * could equally be `/api/v2`, and then the path is
+     * `/api/v2/orders`. Putting the deployed value in and reading the
+     * path back out gets the right one either way.
+     *
+     * Only a hole at the front is a base URL. A hole further along is a
+     * route parameter, and `/orders/{id}` means every id rather than a
+     * variable somebody set.
+     */
+    groundName(semantics, deployedAs) {
+      if (semantics.path === null) {
+        return null;
+      }
+      const opening = OPENING_HOLE.exec(semantics.path);
+      if (opening === null) {
+        return null;
+      }
+      const [, label, rest] = opening;
+      const base = deployedAs(variableOf(label));
+      if (base === null) {
+        return null;
+      }
+      const grounded = pathAfterOrigin(`${base}${rest}`);
+      return { ...semantics, path: grounded === "" ? "/" : grounded };
+    },
     ruleBoundary: {
       // "METHOD /path": one leading token, then an absolute path.
       claims(raw) {

package/dist/schemas.js

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

package/package.json

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