@suss/ir-core 0.8.0 → 0.10.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { T as TypeShape, M as MessageBusSemantics, S as Semantics, B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, d as SourceLocationSchema, e as MessageBusTechnology, D as DeployableUnit } from './schemas-BLS4PXwc.cjs';
-export { f as DeployableUnitSchema, F as FunctionCallSemantics, g as FunctionCallSemanticsSchema, G as GraphqlOperationSemantics, h as GraphqlOperationSemanticsSchema, i as GraphqlResolverSemantics, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, R as RestSemantics, l as RestSemanticsSchema, m as RuntimeConfigSemantics, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, p as StorageSemantics, q as StorageSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as methodsAgree, u as normalizePath, v as routePathAdmits, w as typeDefinitionKey, x as withDefinitionsInlined } from './schemas-BLS4PXwc.cjs';
+import { T as TypeShape, M as MessageBusSemantics, S as Semantics, B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, d as SourceLocationSchema, e as MessageBusTechnology, D as DeployableUnit } from './schemas-CGR6qjFf.cjs';
+export { f as DeployableUnitSchema, F as FunctionCallSemantics, g as FunctionCallSemanticsSchema, G as GraphqlOperationSemantics, h as GraphqlOperationSemanticsSchema, i as GraphqlResolverSemantics, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, R as RestSemantics, l as RestSemanticsSchema, m as RuntimeConfigSemantics, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, p as StorageSemantics, q as StorageSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as methodsAgree, u as normalizePath, v as routePathAdmits, w as typeDefinitionKey, x as withDefinitionsInlined } from './schemas-CGR6qjFf.cjs';
 
 /**
  * Comparing two TypeShapes structurally.
@@ -49,8 +49,33 @@ declare function bodyShapesMatch(actual: TypeShape, declared: TypeShape): MatchR
  * because a published summary has to mean the same thing to a reader
  * who never installed the pack that wrote it. If a pack needs a
  * protocol nobody has defined yet, add a module here.
+ *
+ * A protocol also says which of its words come from OpenTelemetry's
+ * semantic conventions, in `semconv`. The README says why that
+ * matters and where it stops.
  */
 
+/** One identity field written as an OpenTelemetry attribute. */
+interface SemconvAttribute {
+    /** The attribute name, as the semantic conventions spell it. */
+    name: string;
+    /**
+     * Values suss writes where the source named none. A span never says
+     * them, so the projection leaves the attribute off rather than
+     * emitting a string that could only ever mismatch.
+     */
+    placeholderValues?: readonly string[];
+}
+/**
+ * Which identity fields the semantic conventions have an attribute
+ * for. A field is absent when they have no attribute for it, or when
+ * our value is our own string rather than the one a span gets.
+ */
+type SemconvMapping<S extends {
+    name: string;
+}> = {
+    readonly [K in Exclude<keyof S, "name">]?: SemconvAttribute;
+};
 /**
  * How one semantics variant keys its boundaries and pairs them up. Each
  * variant fills this in inside its own module, and nothing else in the
@@ -123,6 +148,11 @@ interface BoundarySemanticsDefinition<Z extends z.ZodType<{
     name: z.infer<Z>["name"];
     schema: Z;
     behavior: BoundaryBehavior<z.infer<Z>>;
+    /**
+     * Every protocol declares this, empty included, so that adding one
+     * means deciding where its words come from.
+     */
+    semconv: SemconvMapping<z.infer<Z>>;
 }
 
 declare const IdentityKeyBrand: unique symbol;
@@ -141,6 +171,39 @@ type BusIdentityKey = `bus:${MessageBusSemantics["messageBus"]} ${string}` & {
     readonly [IdentityKeyBrand]: "bus";
 };
 declare function busIdentityKey(messageBus: MessageBusSemantics["messageBus"], subject: string): BusIdentityKey;
+/** `metric:system type`, the key both sides of a metric pair on. */
+type MetricIdentityKey = `metric:${string} ${string}` & {
+    readonly [IdentityKeyBrand]: "metric";
+};
+declare function metricIdentityKey(metricSystem: string, metricType: string): MetricIdentityKey;
+
+declare const MetricSemanticsSchema: z.ZodObject<{
+    name: z.ZodLiteral<"metric">;
+    metricSystem: z.ZodString;
+    metricType: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type MetricSemantics = z.infer<typeof MetricSemanticsSchema>;
+
+/**
+ * A boundary binding read as OpenTelemetry attributes.
+ *
+ * A summary says what a unit can reach and a span says what it did
+ * reach. Joining the two means both sides spelling the boundary the
+ * same way, so suss writes the value a span gets wherever the semantic
+ * conventions have a word for it, and this projection puts those
+ * values under the attributes a trace store already indexes.
+ *
+ * Which fields those are is each protocol's own declaration, in its
+ * module under `semantics/`. Nothing here knows about any protocol.
+ */
+
+/**
+ * The attributes a boundary states, by name. A field the source never
+ * gave, a placeholder, and a field the conventions have no attribute
+ * for are all left out, so every pair here compares byte for byte
+ * against the same attribute on a span.
+ */
+declare function semconvAttributes(binding: BoundaryBinding): Record<string, string>;
 
 /**
  * Keys for a boundary binding, and whether two of them agree. Every
@@ -180,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.
  *
@@ -262,50 +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, the way a REST
- * path is written with `{id}`, and two names agree when their fixed
- * parts line up.
- *
- * A hole covers a whole parameter rather than one path segment,
- * because a name has no separator that every project agrees on.
- */
-/**
- * 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;
-/**
- * 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.
  *
@@ -545,5 +673,15 @@ declare function messageBusBinding(opts: {
     /** Null when this source does not say which channel. */
     channel: string | null;
 }): BoundaryBinding;
+/**
+ * Build a metric binding, the boundary between whatever declares a
+ * named series of measurements and whatever reads it back by that name.
+ */
+declare function metricBinding(opts: {
+    recognition: string;
+    metricSystem: string;
+    /** Null when this source states a metric it could not name. */
+    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 ParsedChannel, Semantics, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, boundaryLabel, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, hasNameHole, isGraphqlOperationBinding, messageBusBinding, namePatternFromSub, namePatternKey, namesAgree, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseChannel, reportsUnpairedItself, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, 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

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { T as TypeShape, M as MessageBusSemantics, S as Semantics, B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, d as SourceLocationSchema, e as MessageBusTechnology, D as DeployableUnit } from './schemas-BLS4PXwc.js';
-export { f as DeployableUnitSchema, F as FunctionCallSemantics, g as FunctionCallSemanticsSchema, G as GraphqlOperationSemantics, h as GraphqlOperationSemanticsSchema, i as GraphqlResolverSemantics, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, R as RestSemantics, l as RestSemanticsSchema, m as RuntimeConfigSemantics, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, p as StorageSemantics, q as StorageSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as methodsAgree, u as normalizePath, v as routePathAdmits, w as typeDefinitionKey, x as withDefinitionsInlined } from './schemas-BLS4PXwc.js';
+import { T as TypeShape, M as MessageBusSemantics, S as Semantics, B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, d as SourceLocationSchema, e as MessageBusTechnology, D as DeployableUnit } from './schemas-CGR6qjFf.js';
+export { f as DeployableUnitSchema, F as FunctionCallSemantics, g as FunctionCallSemanticsSchema, G as GraphqlOperationSemantics, h as GraphqlOperationSemanticsSchema, i as GraphqlResolverSemantics, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, R as RestSemantics, l as RestSemanticsSchema, m as RuntimeConfigSemantics, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, p as StorageSemantics, q as StorageSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as methodsAgree, u as normalizePath, v as routePathAdmits, w as typeDefinitionKey, x as withDefinitionsInlined } from './schemas-CGR6qjFf.js';
 
 /**
  * Comparing two TypeShapes structurally.
@@ -49,8 +49,33 @@ declare function bodyShapesMatch(actual: TypeShape, declared: TypeShape): MatchR
  * because a published summary has to mean the same thing to a reader
  * who never installed the pack that wrote it. If a pack needs a
  * protocol nobody has defined yet, add a module here.
+ *
+ * A protocol also says which of its words come from OpenTelemetry's
+ * semantic conventions, in `semconv`. The README says why that
+ * matters and where it stops.
  */
 
+/** One identity field written as an OpenTelemetry attribute. */
+interface SemconvAttribute {
+    /** The attribute name, as the semantic conventions spell it. */
+    name: string;
+    /**
+     * Values suss writes where the source named none. A span never says
+     * them, so the projection leaves the attribute off rather than
+     * emitting a string that could only ever mismatch.
+     */
+    placeholderValues?: readonly string[];
+}
+/**
+ * Which identity fields the semantic conventions have an attribute
+ * for. A field is absent when they have no attribute for it, or when
+ * our value is our own string rather than the one a span gets.
+ */
+type SemconvMapping<S extends {
+    name: string;
+}> = {
+    readonly [K in Exclude<keyof S, "name">]?: SemconvAttribute;
+};
 /**
  * How one semantics variant keys its boundaries and pairs them up. Each
  * variant fills this in inside its own module, and nothing else in the
@@ -123,6 +148,11 @@ interface BoundarySemanticsDefinition<Z extends z.ZodType<{
     name: z.infer<Z>["name"];
     schema: Z;
     behavior: BoundaryBehavior<z.infer<Z>>;
+    /**
+     * Every protocol declares this, empty included, so that adding one
+     * means deciding where its words come from.
+     */
+    semconv: SemconvMapping<z.infer<Z>>;
 }
 
 declare const IdentityKeyBrand: unique symbol;
@@ -141,6 +171,39 @@ type BusIdentityKey = `bus:${MessageBusSemantics["messageBus"]} ${string}` & {
     readonly [IdentityKeyBrand]: "bus";
 };
 declare function busIdentityKey(messageBus: MessageBusSemantics["messageBus"], subject: string): BusIdentityKey;
+/** `metric:system type`, the key both sides of a metric pair on. */
+type MetricIdentityKey = `metric:${string} ${string}` & {
+    readonly [IdentityKeyBrand]: "metric";
+};
+declare function metricIdentityKey(metricSystem: string, metricType: string): MetricIdentityKey;
+
+declare const MetricSemanticsSchema: z.ZodObject<{
+    name: z.ZodLiteral<"metric">;
+    metricSystem: z.ZodString;
+    metricType: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type MetricSemantics = z.infer<typeof MetricSemanticsSchema>;
+
+/**
+ * A boundary binding read as OpenTelemetry attributes.
+ *
+ * A summary says what a unit can reach and a span says what it did
+ * reach. Joining the two means both sides spelling the boundary the
+ * same way, so suss writes the value a span gets wherever the semantic
+ * conventions have a word for it, and this projection puts those
+ * values under the attributes a trace store already indexes.
+ *
+ * Which fields those are is each protocol's own declaration, in its
+ * module under `semantics/`. Nothing here knows about any protocol.
+ */
+
+/**
+ * The attributes a boundary states, by name. A field the source never
+ * gave, a placeholder, and a field the conventions have no attribute
+ * for are all left out, so every pair here compares byte for byte
+ * against the same attribute on a span.
+ */
+declare function semconvAttributes(binding: BoundaryBinding): Record<string, string>;
 
 /**
  * Keys for a boundary binding, and whether two of them agree. Every
@@ -180,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.
  *
@@ -262,50 +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, the way a REST
- * path is written with `{id}`, and two names agree when their fixed
- * parts line up.
- *
- * A hole covers a whole parameter rather than one path segment,
- * because a name has no separator that every project agrees on.
- */
-/**
- * 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;
-/**
- * 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.
  *
@@ -545,5 +673,15 @@ declare function messageBusBinding(opts: {
     /** Null when this source does not say which channel. */
     channel: string | null;
 }): BoundaryBinding;
+/**
+ * Build a metric binding, the boundary between whatever declares a
+ * named series of measurements and whatever reads it back by that name.
+ */
+declare function metricBinding(opts: {
+    recognition: string;
+    metricSystem: string;
+    /** Null when this source states a metric it could not name. */
+    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 ParsedChannel, Semantics, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, boundaryLabel, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, hasNameHole, isGraphqlOperationBinding, messageBusBinding, namePatternFromSub, namePatternKey, namesAgree, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseChannel, reportsUnpairedItself, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, 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 };