@suss/ir-core 0.8.0 → 0.10.0

package/README.md

@@ -31,6 +31,71 @@ 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.
 
+## Boundary names
+
+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 **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.
+
+`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.
+
+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.
+
+### 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
+
+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-HBAMPBAO.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,30 @@ 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.
+   * 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: 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 +515,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 +537,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 +554,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 +612,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 +701,7 @@ export {
   gqlIdentityKey,
   fnIdentityKey,
   busIdentityKey,
+  metricIdentityKey,
   FunctionCallSemanticsSchema,
   GraphqlResolverSemanticsSchema,
   parseChannel,
@@ -625,6 +709,7 @@ export {
   busesAgree,
   channelsPair,
   MessageBusSemanticsSchema,
+  MetricSemanticsSchema,
   RestSemanticsSchema,
   normalizePath,
   methodsAgree,
@@ -635,6 +720,7 @@ export {
   StorageSemanticsSchema,
   SemanticsSchema,
   behaviorOf,
+  semconvMappingOf,
   allBehaviors,
   ConfidenceSourceSchema,
   ConfidenceLevelSchema,