@suss/ir-core 0.8.0 → 0.9.0

package/README.md

@@ -31,6 +31,49 @@ 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
+
+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 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 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.
+
+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.
+
+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.
+
+## Words OpenTelemetry already has
+
+A summary says what a unit can reach. A trace says what it did reach. Comparing the two is the point, and it only works if both sides spell a boundary the same way, so wherever OpenTelemetry's semantic conventions have a word for something in a binding, that is the word suss writes.
+
+The values are theirs. A Postgres table is `postgresql`, not `postgres`; a DynamoDB table is `aws.dynamodb`; an SQS queue is `aws_sqs` and an SNS topic is `aws.sns`, spelled the two different ways the conventions spell them.
+
+The field names are ours. Each protocol module says which attribute each of its fields goes under, and `semconvAttributes(binding)` reads a binding as the attributes a span would state:
+
+```ts
+semconvAttributes(
+  storageBinding({
+    recognition: "prisma",
+    storageSystem: "postgresql",
+    scope: "orders",
+    container: "users",
+  }),
+);
+// { "db.system.name": "postgresql", "db.namespace": "orders",
+//   "db.collection.name": "users" }
+```
+
+A field appears in that projection only when the value suss writes is the value a span gets, so the comparison is byte for byte with nothing in between. Three kinds of field stay out of it:
+
+- **A field the conventions have no attribute for.** A secondary index (`accessPath`) is one, and a GraphQL resolver's type and field are another, since the conventions describe the operation a client sent and not the resolver the server ran for one field of it.
+- **A value suss writes where the source stated none.** `scope: "default"` means no source said which database, and a REST method of `"*"` means the route responds to every method. A span says neither.
+- **The same thing under a different string.** `service.name` and `cloud.resource_id` both point at the deployable a `runtime-config` boundary belongs to, but `instanceName` is the deployment template's logical id, which is neither of those strings.
+
+Where the conventions have no word at all, suss keeps its own: a store they never covered (`s3`, `gcs`, `r2`, `d1`, `cloudflare-kv`), a bus they never covered (`eventbridge`, `bullmq`, `nats`, the Cloudflare triggers), a metric's system and type, and every boundary nobody crosses at run time, which is a function call across a package boundary, a contract a template declares, and an intent. Those are the boundaries suss exists for, and no observability convention has a word for them.
+
+Adding a protocol means filling in `semconv` on its definition, empty included, so the question gets answered rather than skipped.
+
 ## Where it fits in suss
 
 Both `@suss/behavioral-ir` (what code does) and `@suss/intent-ir` (what the team meant) build on this package, so neither IR depends on the other. They describe boundaries in the same vocabulary, and suss compares them rather than merging them. `@suss/behavioral-ir` re-exports these primitives, so existing consumers keep importing them from there unchanged.

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

@@ -1,8 +1,8 @@
 // src/schemas.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 
 // src/semantics/registry.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 
 // src/semantics/functionCall.ts
 import { z } from "zod";
@@ -17,6 +17,9 @@ function fnIdentityKey(packageName, exportPath) {
 function busIdentityKey(messageBus, subject) {
   return `bus:${messageBus} ${subject}`;
 }
+function metricIdentityKey(metricSystem, metricType) {
+  return `metric:${metricSystem} ${metricType}`;
+}
 
 // src/semantics/definition.ts
 function defineBoundarySemantics(definition) {
@@ -58,6 +61,9 @@ var FunctionCallSemanticsSchema = z.object({
 var functionCallSemantics = defineBoundarySemantics({
   name: "function-call",
   schema: FunctionCallSemanticsSchema,
+  // A call that never leaves the process does not produce a span, and
+  // the conventions do not name one. All of it is ours.
+  semconv: {},
   behavior: {
     /** A call returns a value, which is not a status and a body. */
     exchangesHttpResponses: false,
@@ -93,6 +99,10 @@ var GraphqlOperationSemanticsSchema = z2.object({
 var graphqlOperationSemantics = defineBoundarySemantics({
   name: "graphql-operation",
   schema: GraphqlOperationSemanticsSchema,
+  semconv: {
+    operationName: { name: "graphql.operation.name" },
+    operationType: { name: "graphql.operation.type" }
+  },
   behavior: {
     /**
      * An operation gets a data-and-errors document back, which the
@@ -126,6 +136,9 @@ var GraphqlResolverSemanticsSchema = z3.object({
 var graphqlResolverSemantics = defineBoundarySemantics({
   name: "graphql-resolver",
   schema: GraphqlResolverSemanticsSchema,
+  // The conventions name the operation a client sent, not the
+  // resolver the server ran for one field of it.
+  semconv: {},
   behavior: {
     /** A resolver returns a field value, not a status and a body. */
     exchangesHttpResponses: false,
@@ -174,8 +187,11 @@ function channelsPair(a, b) {
 var MessageBusSemanticsSchema = z4.object({
   name: z4.literal("message-bus"),
   messageBus: z4.enum([
-    "sqs",
-    "sns",
+    // The conventions spell the two AWS buses this way, one with an
+    // underscore and one with a dot, so these are their strings and
+    // not a typo.
+    "aws_sqs",
+    "aws.sns",
     "s3",
     "eventbridge",
     "bullmq",
@@ -196,6 +212,10 @@ var MessageBusSemanticsSchema = z4.object({
 var messageBusSemantics = defineBoundarySemantics({
   name: "message-bus",
   schema: MessageBusSemanticsSchema,
+  semconv: {
+    messageBus: { name: "messaging.system" },
+    channel: { name: "messaging.destination.name" }
+  },
   behavior: {
     /** A message goes onto the channel and nothing comes back. */
     exchangesHttpResponses: false,
@@ -254,25 +274,58 @@ var messageBusSemantics = defineBoundarySemantics({
   }
 });
 
-// src/semantics/rest.ts
+// src/semantics/metric.ts
 import { z as z5 } from "zod";
-var RestSemanticsSchema = z5.object({
-  name: z5.literal("rest"),
+var MetricSemanticsSchema = z5.object({
+  name: z5.literal("metric"),
+  /** Which system the series lives in: cloud-monitoring, cloudwatch. */
+  metricSystem: z5.string(),
+  /**
+   * The type string the system knows the metric by, spelled the way
+   * both sides spell it. Null when the source states one this reader
+   * could not settle, as with a query it could not read: a metric
+   * nobody could name pairs with nothing rather than with whatever
+   * happens to share its source text.
+   */
+  metricType: z5.string().nullable()
+});
+var metricSemantics = defineBoundarySemantics({
+  name: "metric",
+  schema: MetricSemanticsSchema,
+  // OpenTelemetry knows a metric by its instrument name, and has no
+  // attribute for the system it lives in or the type string it goes by.
+  semconv: {},
+  behavior: {
+    exchangesHttpResponses: false,
+    reportsUnpairedItself: false,
+    identityKey(semantics) {
+      if (semantics.metricType === null) {
+        return null;
+      }
+      return metricIdentityKey(semantics.metricSystem, semantics.metricType);
+    }
+  }
+});
+
+// src/semantics/rest.ts
+import { z as z6 } from "zod";
+var RestSemanticsSchema = z6.object({
+  name: z6.literal("rest"),
   /**
    * Uppercase HTTP method ("GET", "POST", …), `"*"` for a handler that
    * responds to every method, or null when this source does not say
    * which method.
    */
-  method: z5.string().min(1).nullable(),
+  method: z6.string().min(1).nullable(),
   /** Normalized route path ("/users/{id}"), or null when this source does not give one. */
-  path: z5.string().min(1).nullable(),
+  path: z6.string().min(1).nullable(),
   /**
    * Status codes the producing source explicitly declared (OpenAPI
    * responses, CFN MethodResponses, ts-rest router statuses). They are
    * kept here so the pairing layer can see them without unwrapping any
    * metadata. Absent, or empty, for a source that was inferred.
    */
-  declaredResponses: z5.array(z5.number()).optional()
+  declaredResponses: z6.array(z6.number()).optional()
 });
 function normalizePath(path) {
   let normalized = path.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
@@ -311,6 +364,14 @@ function routePathAdmits(declaredPath, requestPath) {
 var restSemantics = defineBoundarySemantics({
   name: "rest",
   schema: RestSemanticsSchema,
+  semconv: {
+    // A span states the one method a request used, so a route that
+    // responds to every method has nothing to compare.
+    method: { name: "http.request.method", placeholderValues: ["*"] },
+    path: { name: "http.route" }
+    // declaredResponses is a list, and http.response.status_code is
+    // the one status a request got back.
+  },
   behavior: {
     /** A request goes out, a status and a body come back. */
     exchangesHttpResponses: true,
@@ -383,12 +444,12 @@ var restSemantics = defineBoundarySemantics({
 });
 
 // src/semantics/runtimeConfig.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 
 // src/deployableUnit.ts
-import { z as z6 } from "zod";
-var DeployableUnitSchema = z6.object({
-  deploymentTarget: z6.enum([
+import { z as z7 } from "zod";
+var DeployableUnitSchema = z7.object({
+  deploymentTarget: z7.enum([
     "lambda",
     "ecs-task",
     "container",
@@ -397,7 +458,7 @@ var DeployableUnitSchema = z6.object({
   ]),
   // An empty name would agree with every other empty name, so a unit
   // with no name has to leave the field off instead.
-  instanceName: z6.string().min(1)
+  instanceName: z7.string().min(1)
 });
 function ecsContainerInstanceName(taskDefinitionLogicalId, containerName) {
   return `${taskDefinitionLogicalId}/${containerName}`;
@@ -405,11 +466,15 @@ function ecsContainerInstanceName(taskDefinitionLogicalId, containerName) {
 
 // src/semantics/runtimeConfig.ts
 var RuntimeConfigSemanticsSchema = DeployableUnitSchema.extend({
-  name: z7.literal("runtime-config")
+  name: z8.literal("runtime-config")
 });
 var runtimeConfigSemantics = defineBoundarySemantics({
   name: "runtime-config",
   schema: RuntimeConfigSemanticsSchema,
+  // service.name and cloud.resource_id name the same deployable, but
+  // instanceName is the deployment template's logical id, which is
+  // neither of those strings.
+  semconv: {},
   behavior: {
     /** A process reads its config at startup, and nothing replies. */
     exchangesHttpResponses: false,
@@ -419,28 +484,28 @@ var runtimeConfigSemantics = defineBoundarySemantics({
 });
 
 // src/semantics/storage.ts
-import { z as z8 } from "zod";
-var StorageSemanticsSchema = z8.object({
-  name: z8.literal("storage"),
+import { z as z9 } from "zod";
+var StorageSemanticsSchema = z9.object({
+  name: z9.literal("storage"),
   /**
-   * Which store this is: postgres, mysql, sqlite, dynamodb. Two
-   * products' containers can share a name, so this keeps them apart,
-   * and it is what a finding message calls the store.
+   * Which store this is: postgresql, mysql, aws.dynamodb, or our own
+   * word for one OpenTelemetry never named, such as s3. Two products'
+   * containers can share a name, so this keeps them apart.
    */
-  storageSystem: z8.string(),
+  storageSystem: z9.string(),
   /**
    * The ORM, schema, or deployment scope. A single-database setup uses
    * `"default"`, and a monorepo with several schemas gives each one its
    * own value.
    */
-  scope: z8.string(),
+  scope: z9.string(),
   /**
    * The table, bucket, collection, or index, as the source declares
    * it, or null when the source states one this reader could not
    * settle. A null container pairs with nothing, rather than with
    * whatever its source text happens to spell.
    */
-  container: z8.string().nullable(),
+  container: z9.string().nullable(),
   /**
    * A secondary way into the container, a DynamoDB global secondary
    * index or an Elasticsearch alias, each with its own key fields.
@@ -448,11 +513,19 @@ var StorageSemanticsSchema = z8.object({
    * index and a query through the table are different accesses, so
    * they pair separately.
    */
-  accessPath: z8.string().nullable()
+  accessPath: z9.string().nullable()
 });
 var storageSemantics = defineBoundarySemantics({
   name: "storage",
   schema: StorageSemanticsSchema,
+  semconv: {
+    storageSystem: { name: "db.system.name" },
+    // "default" is our word for a source that named no database.
+    scope: { name: "db.namespace", placeholderValues: ["default"] },
+    container: { name: "db.collection.name" }
+    // A secondary index has no attribute of its own, so accessPath
+    // stays our word.
+  },
   behavior: {
     /** A query returns rows or items, not a status and a body. */
     exchangesHttpResponses: false,
@@ -462,14 +535,15 @@ var storageSemantics = defineBoundarySemantics({
 });
 
 // src/semantics/registry.ts
-var SemanticsSchema = z9.discriminatedUnion("name", [
+var SemanticsSchema = z10.discriminatedUnion("name", [
   restSemantics.schema,
   functionCallSemantics.schema,
   graphqlResolverSemantics.schema,
   graphqlOperationSemantics.schema,
   runtimeConfigSemantics.schema,
   storageSemantics.schema,
-  messageBusSemantics.schema
+  messageBusSemantics.schema,
+  metricSemantics.schema
 ]);
 var DEFINITIONS = [
   restSemantics,
@@ -478,48 +552,55 @@ var DEFINITIONS = [
   graphqlOperationSemantics,
   runtimeConfigSemantics,
   storageSemantics,
-  messageBusSemantics
+  messageBusSemantics,
+  metricSemantics
 ];
 var BY_NAME = new Map(
   DEFINITIONS.map((d) => [d.name, d])
 );
 function behaviorOf(semantics) {
-  const definition = BY_NAME.get(semantics.name);
+  return definitionFor(semantics.name).behavior;
+}
+function definitionFor(name) {
+  const definition = BY_NAME.get(name);
   if (definition === void 0) {
-    throw new Error(`no boundary behavior for semantics "${semantics.name}"`);
+    throw new Error(`no boundary definition for semantics "${name}"`);
   }
-  return definition.behavior;
+  return definition;
+}
+function semconvMappingOf(semantics) {
+  return definitionFor(semantics.name).semconv;
 }
 function allBehaviors() {
   return DEFINITIONS.map((d) => d.behavior);
 }
 
 // src/schemas.ts
-var ConfidenceSourceSchema = z10.enum([
+var ConfidenceSourceSchema = z11.enum([
   "inferred_static",
   "inferred_ai",
   "declared",
   "derived"
 ]);
-var ConfidenceLevelSchema = z10.enum(["high", "medium", "low"]);
-var CorroborationSchema = z10.object({
-  outcome: z10.enum(["observed", "refuted", "untested"]),
+var ConfidenceLevelSchema = z11.enum(["high", "medium", "low"]);
+var CorroborationSchema = z11.object({
+  outcome: z11.enum(["observed", "refuted", "untested"]),
   /** Executions that produced a verdict for this claim. */
-  runs: z10.number(),
+  runs: z11.number(),
   /** Present when refuted: the input and observation that disagreed. */
-  counterexample: z10.unknown().optional(),
+  counterexample: z11.unknown().optional(),
   /** Present when untested: why no verdict was reachable. */
-  reason: z10.string().optional()
+  reason: z11.string().optional()
 });
-var ConfidenceInfoSchema = z10.object({
+var ConfidenceInfoSchema = z11.object({
   source: ConfidenceSourceSchema,
   level: ConfidenceLevelSchema,
   corroboration: CorroborationSchema.optional()
 });
-var SourceLocationSchema = z10.object({
-  file: z10.string(),
-  range: z10.object({ start: z10.number(), end: z10.number() }),
-  exportName: z10.string().nullable(),
+var SourceLocationSchema = z11.object({
+  file: z11.string(),
+  range: z11.object({ start: z11.number(), end: z11.number() }),
+  exportName: z11.string().nullable(),
   /**
    * The project the extract was pointed at, by the name that project
    * calls itself.
@@ -529,47 +610,47 @@ var SourceLocationSchema = z10.object({
    * summaries puts them on top of each other. This field is what tells
    * them apart, and what a reader groups by.
    */
-  workspace: z10.string().optional()
+  workspace: z11.string().optional()
 });
-var BoundaryBindingSchema = z10.object({
-  transport: z10.string(),
+var BoundaryBindingSchema = z11.object({
+  transport: z11.string(),
   semantics: SemanticsSchema,
-  recognition: z10.string()
+  recognition: z11.string()
 });
 function typeDefinitionKey(ref) {
   return ref.def ?? null;
 }
-var TypeShapeSchema = z10.lazy(
-  () => z10.discriminatedUnion("type", [
-    z10.object({
-      type: z10.literal("record"),
-      properties: z10.record(z10.string(), TypeShapeSchema),
-      spreads: z10.array(z10.object({ sourceText: z10.string() })).optional()
+var TypeShapeSchema = z11.lazy(
+  () => z11.discriminatedUnion("type", [
+    z11.object({
+      type: z11.literal("record"),
+      properties: z11.record(z11.string(), TypeShapeSchema),
+      spreads: z11.array(z11.object({ sourceText: z11.string() })).optional()
     }),
-    z10.object({ type: z10.literal("dictionary"), values: TypeShapeSchema }),
-    z10.object({ type: z10.literal("array"), items: TypeShapeSchema }),
-    z10.object({
-      type: z10.literal("literal"),
-      value: z10.union([z10.string(), z10.number(), z10.boolean()]),
-      raw: z10.string().optional()
+    z11.object({ type: z11.literal("dictionary"), values: TypeShapeSchema }),
+    z11.object({ type: z11.literal("array"), items: TypeShapeSchema }),
+    z11.object({
+      type: z11.literal("literal"),
+      value: z11.union([z11.string(), z11.number(), z11.boolean()]),
+      raw: z11.string().optional()
     }),
-    z10.object({ type: z10.literal("text") }),
-    z10.object({ type: z10.literal("integer") }),
-    z10.object({ type: z10.literal("number") }),
-    z10.object({ type: z10.literal("boolean") }),
-    z10.object({ type: z10.literal("null") }),
-    z10.object({ type: z10.literal("undefined") }),
-    z10.object({
-      type: z10.literal("union"),
-      variants: z10.array(TypeShapeSchema)
+    z11.object({ type: z11.literal("text") }),
+    z11.object({ type: z11.literal("integer") }),
+    z11.object({ type: z11.literal("number") }),
+    z11.object({ type: z11.literal("boolean") }),
+    z11.object({ type: z11.literal("null") }),
+    z11.object({ type: z11.literal("undefined") }),
+    z11.object({
+      type: z11.literal("union"),
+      variants: z11.array(TypeShapeSchema)
     }),
-    z10.object({
-      type: z10.literal("ref"),
-      name: z10.string(),
-      from: z10.string().optional(),
-      def: z10.string().optional()
+    z11.object({
+      type: z11.literal("ref"),
+      name: z11.string(),
+      from: z11.string().optional(),
+      def: z11.string().optional()
     }),
-    z10.object({ type: z10.literal("unknown") })
+    z11.object({ type: z11.literal("unknown") })
   ])
 );
 var MAX_DEFINITION_DEPTH = 6;
@@ -618,6 +699,7 @@ export {
   gqlIdentityKey,
   fnIdentityKey,
   busIdentityKey,
+  metricIdentityKey,
   FunctionCallSemanticsSchema,
   GraphqlResolverSemanticsSchema,
   parseChannel,
@@ -625,6 +707,7 @@ export {
   busesAgree,
   channelsPair,
   MessageBusSemanticsSchema,
+  MetricSemanticsSchema,
   RestSemanticsSchema,
   normalizePath,
   methodsAgree,
@@ -635,6 +718,7 @@ export {
   StorageSemanticsSchema,
   SemanticsSchema,
   behaviorOf,
+  semconvMappingOf,
   allBehaviors,
   ConfidenceSourceSchema,
   ConfidenceLevelSchema,