@suss/ir-core 0.3.1 → 0.4.0

package/dist/index.js

@@ -15,69 +15,63 @@ import {
   SourceLocationSchema,
   StorageRelationalSemanticsSchema,
   TypeShapeSchema,
+  allBehaviors,
+  behaviorOf,
+  busesAgree,
+  channelsPair,
+  ecsContainerInstanceName,
+  formatChannel,
+  methodsAgree,
+  normalizePath,
+  parseChannel,
+  routePathAdmits,
   typeDefinitionKey,
   withDefinitionsInlined
-} from "./chunk-L4XGOS3I.js";
+} from "./chunk-5KE7OWN3.js";
 
-// src/channel.ts
-function parseChannel(channel) {
-  const hash = channel.indexOf("#");
-  if (hash === -1) {
-    return { bus: null, subject: channel };
-  }
-  return { bus: channel.slice(0, hash), subject: channel.slice(hash + 1) };
+// src/boundaryKey.ts
+function boundaryKey(binding) {
+  return behaviorOf(binding.semantics).identityKey(binding.semantics);
 }
-function busesAgree(a, b) {
-  return a === null || b === null || a === b;
+function pairingKey(binding) {
+  const behavior = behaviorOf(binding.semantics);
+  return (behavior.pairingKey ?? behavior.identityKey)(binding.semantics);
 }
-function channelsPair(a, b) {
-  const left = parseChannel(a);
-  const right = parseChannel(b);
-  return left.subject === right.subject && busesAgree(left.bus, right.bus);
+function semanticsAgree(a, b) {
+  if (a.name !== b.name) {
+    return false;
+  }
+  const agree = behaviorOf(a).sidesAgree;
+  return agree === void 0 ? true : agree(a, b);
 }
-
-// src/boundaryKey.ts
-function normalizePath(path) {
-  let normalized = path.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
-  if (normalized.length > 1 && normalized.endsWith("/")) {
-    normalized = normalized.slice(0, -1);
-  }
-  normalized = normalized.replace(
-    /\{[^}]+\}|[^{]+/g,
-    (segment) => segment.startsWith("{") ? segment : segment.toLowerCase()
-  );
-  return normalized;
+function boundaryLabel(binding) {
+  const behavior = behaviorOf(binding.semantics);
+  return (behavior.displayLabel ?? behavior.identityKey)(binding.semantics);
 }
-function boundaryKey(binding) {
-  const semantics = binding.semantics;
-  if (semantics.name === "rest") {
-    if (semantics.method === "" || semantics.path === "") {
-      return null;
-    }
-    const method = semantics.method.toUpperCase();
-    const path = normalizePath(semantics.path);
-    return `${method} ${path}`;
-  }
-  if (semantics.name === "graphql-resolver") {
-    if (semantics.typeName === "" || semantics.fieldName === "") {
-      return null;
-    }
-    return `gql:${semantics.typeName}.${semantics.fieldName}`;
-  }
-  if (semantics.name === "message-bus") {
-    const { subject } = parseChannel(semantics.channel);
-    if (subject === "") {
-      return null;
+function displayLabel(binding) {
+  return boundaryLabel(binding) ?? `${binding.semantics.name}:${binding.recognition}`;
+}
+function normalizeRuleBoundary(raw) {
+  const trimmed = raw.trim();
+  for (const behavior of allBehaviors()) {
+    if (behavior.ruleBoundary?.claims(trimmed) === true) {
+      return behavior.ruleBoundary.normalize(trimmed);
     }
-    return `bus:${semantics.messageBus} ${subject}`;
   }
-  if (semantics.name === "function-call") {
-    if (semantics.package !== void 0 && semantics.exportPath !== void 0 && semantics.exportPath.length > 0) {
-      return `fn:${semantics.package}::${semantics.exportPath.join(".")}`;
-    }
+  return trimmed;
+}
+function exchangesHttpResponses(binding) {
+  return behaviorOf(binding.semantics).exchangesHttpResponses;
+}
+function reportsUnpairedItself(binding) {
+  return behaviorOf(binding.semantics).reportsUnpairedItself;
+}
+function servesRequest(binding, method, path) {
+  const serves = behaviorOf(binding.semantics).servesRequest;
+  if (serves === void 0) {
     return null;
   }
-  return null;
+  return serves(binding.semantics, method, path);
 }
 
 // src/codeScope.ts
@@ -107,9 +101,9 @@ var SuppressionSideSchema = z.object({
 }).optional();
 var SuppressionRuleSchema = z.object({
   /**
-   * Finding kind to match — any behavioural or intent finding kind.
-   * Open here (this package sits below both IRs); the loader
-   * validates against the published kind enums.
+   * The finding kind to match, behavioural or intent. It is an open
+   * string here because this package is below both IRs, and the loader
+   * is what validates it against the published kind enums.
    */
   kind: z.string().optional(),
   /**
@@ -120,26 +114,26 @@ var SuppressionRuleSchema = z.object({
    */
   boundary: z.string().optional(),
   /**
-   * Consumer-side discriminators (narrowest useful match). Only
-   * meaningful for behavioural findings — a rule that specifies
-   * `consumer` never matches an intent finding, which has no
-   * consumer side.
+   * Consumer-side discriminators, the narrowest useful match. These
+   * mean something only for behavioural findings: a rule that
+   * specifies `consumer` never matches an intent finding, because an
+   * intent finding has no consumer side.
    */
   consumer: SuppressionSideSchema,
   /**
    * Provider-side discriminators, the mirror of `consumer`. A finding
-   * about a status the provider produces carries its transition id on
-   * this side, and that id is the only handle narrow enough to name
-   * that one finding. Like `consumer`, a rule that specifies
+   * about a status the provider produces has its transition id on this
+   * side, and that id is the only handle narrow enough to pick out
+   * that one finding. As with `consumer`, a rule that specifies
    * `provider` never matches an intent finding.
    */
   provider: SuppressionSideSchema,
   /**
-   * "narrow" (default): requires kind plus one of boundary,
-   * consumer.transitionId, or provider.transitionId — enough to
-   * target a specific finding class. "broad" opts in to kind-only or
-   * boundary-only matches, which silence future regressions in that
-   * category too.
+   * "narrow", the default, requires kind plus one of boundary,
+   * consumer.transitionId, or provider.transitionId, which is enough
+   * to target a specific class of finding. "broad" opts in to
+   * kind-only or boundary-only matches, which also silence future
+   * regressions in that category.
    */
   scope: z.enum(["narrow", "broad"]).default("narrow"),
   /** Required human-written justification. */
@@ -166,16 +160,6 @@ function validateRule(rule) {
   }
   return "narrow-scope rule must specify kind AND (boundary OR consumer.transitionId OR provider.transitionId); set scope: 'broad' to silence wider categories";
 }
-function normalizeRuleBoundary(raw) {
-  const trimmed = raw.trim();
-  const spaceIdx = trimmed.indexOf(" ");
-  if (spaceIdx < 0) {
-    return trimmed;
-  }
-  const method = trimmed.slice(0, spaceIdx).toUpperCase();
-  const path = trimmed.slice(spaceIdx + 1);
-  return `${method} ${normalizePath(path)}`;
-}
 function ruleBoundaryMatchesKey(ruleBoundary, key) {
   if (key === null) {
     return false;
@@ -371,13 +355,22 @@ function allowsUndefined(shape) {
 }
 
 // src/index.ts
+function namedOrNull(value, field) {
+  if (value === "") {
+    throw new Error(
+      `${field} is an empty string; write null when the source does not name it`
+    );
+  }
+  return value;
+}
 function restBinding(opts) {
+  const method = namedOrNull(opts.method, "rest method");
   return {
     transport: opts.transport,
     semantics: {
       name: "rest",
-      method: opts.method.toUpperCase(),
-      path: opts.path,
+      method: method === null ? null : method.toUpperCase(),
+      path: namedOrNull(opts.path, "rest path"),
       ...opts.declaredResponses !== void 0 ? { declaredResponses: opts.declaredResponses } : {}
     },
     recognition: opts.recognition
@@ -409,7 +402,7 @@ function graphqlResolverBinding(opts) {
     transport: opts.transport,
     semantics: {
       name: "graphql-resolver",
-      typeName: opts.typeName,
+      typeName: namedOrNull(opts.typeName, "resolver typeName"),
       fieldName: opts.fieldName
     },
     recognition: opts.recognition
@@ -455,7 +448,7 @@ function messageBusBinding(opts) {
     semantics: {
       name: "message-bus",
       messageBus: opts.messageBus,
-      channel: opts.channel
+      channel: namedOrNull(opts.channel, "message-bus channel")
     },
     recognition: opts.recognition
   };
@@ -482,23 +475,34 @@ export {
   applySuppressionsToFindings,
   bodyShapesMatch,
   boundaryKey,
+  boundaryLabel,
   busesAgree,
   channelsPair,
   codeScopePath,
   countsForThreshold,
   dispatchByType,
+  displayLabel,
+  ecsContainerInstanceName,
+  exchangesHttpResponses,
   fileInCodeScope,
+  formatChannel,
   functionCallBinding,
   graphqlOperationBinding,
   graphqlResolverBinding,
   messageBusBinding,
+  methodsAgree,
   normalizePath,
   normalizeRuleBoundary,
   packageExportBinding,
+  pairingKey,
   parseChannel,
+  reportsUnpairedItself,
   restBinding,
+  routePathAdmits,
   ruleBoundaryMatchesKey,
   runtimeConfigBinding,
+  semanticsAgree,
+  servesRequest,
   storageRelationalBinding,
   typeDefinitionKey,
   validateRule,

package/dist/schemas-BWvfkxSH.d.cts

@@ -0,0 +1,432 @@
+import { z } from 'zod';
+
+/**
+ * One thing that gets deployed and runs on its own: a Lambda function,
+ * an ECS task's container, a plain container, or a k8s deployment.
+ */
+
+/**
+ * `instanceName` is the stable identifier the deployment medium uses:
+ * the CFN logical resource id for Lambda and ECS, the deployment name
+ * for k8s, the container name for a plain container.
+ */
+declare const DeployableUnitSchema: z.ZodObject<{
+    deploymentTarget: z.ZodEnum<{
+        lambda: "lambda";
+        "ecs-task": "ecs-task";
+        container: "container";
+        "k8s-deployment": "k8s-deployment";
+    }>;
+    instanceName: z.ZodString;
+}, z.core.$strip>;
+type DeployableUnit = z.infer<typeof DeployableUnitSchema>;
+/**
+ * The `instanceName` for an ECS task's container: the task definition's
+ * own logical id, plus the container name from CFN's
+ * `ContainerDefinitions[*].Name`. Everyone who writes an ECS
+ * `DeployableUnit`, and everyone who matches a routing edge against
+ * one, has to put the two together the same way, so they all call this.
+ */
+declare function ecsContainerInstanceName(taskDefinitionLogicalId: string, containerName: string): string;
+
+declare const FunctionCallSemanticsSchema: z.ZodObject<{
+    name: z.ZodLiteral<"function-call">;
+    module: z.ZodOptional<z.ZodString>;
+    exportName: z.ZodOptional<z.ZodString>;
+    package: z.ZodOptional<z.ZodString>;
+    exportPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type FunctionCallSemantics = z.infer<typeof FunctionCallSemanticsSchema>;
+
+declare const GraphqlOperationSemanticsSchema: z.ZodObject<{
+    name: z.ZodLiteral<"graphql-operation">;
+    operationName: z.ZodOptional<z.ZodString>;
+    operationType: z.ZodEnum<{
+        query: "query";
+        mutation: "mutation";
+        subscription: "subscription";
+    }>;
+}, z.core.$strip>;
+type GraphqlOperationSemantics = z.infer<typeof GraphqlOperationSemanticsSchema>;
+
+declare const GraphqlResolverSemanticsSchema: z.ZodObject<{
+    name: z.ZodLiteral<"graphql-resolver">;
+    typeName: z.ZodNullable<z.ZodString>;
+    fieldName: z.ZodString;
+}, z.core.$strip>;
+type GraphqlResolverSemantics = z.infer<typeof GraphqlResolverSemanticsSchema>;
+
+declare const MessageBusSemanticsSchema: z.ZodObject<{
+    name: z.ZodLiteral<"message-bus">;
+    messageBus: z.ZodEnum<{
+        sqs: "sqs";
+        sns: "sns";
+        s3: "s3";
+        eventbridge: "eventbridge";
+        bullmq: "bullmq";
+        kafka: "kafka";
+        nats: "nats";
+    }>;
+    channel: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type MessageBusSemantics = z.infer<typeof MessageBusSemanticsSchema>;
+/**
+ * The bus technologies the schema allows. It comes from the enum, so a
+ * value added there cannot drift from a hand-written copy elsewhere.
+ */
+type MessageBusTechnology = MessageBusSemantics["messageBus"];
+
+/**
+ * Where the protocol modules come together.
+ *
+ * Each protocol under this directory exports one
+ * `BoundarySemanticsDefinition`. This file lists them twice, once for
+ * the schema union and once for the behavior lookup, and the type check
+ * at the bottom fails compilation if the two lists ever cover different
+ * sets. Adding a protocol changes this file and no other, by one line in
+ * each list.
+ */
+
+/**
+ * The discriminated union every boundary binding validates against.
+ * Built from the protocol modules' own schemas.
+ */
+declare const SemanticsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    name: z.ZodLiteral<"rest">;
+    method: z.ZodNullable<z.ZodString>;
+    path: z.ZodNullable<z.ZodString>;
+    declaredResponses: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodLiteral<"function-call">;
+    module: z.ZodOptional<z.ZodString>;
+    exportName: z.ZodOptional<z.ZodString>;
+    package: z.ZodOptional<z.ZodString>;
+    exportPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodLiteral<"graphql-resolver">;
+    typeName: z.ZodNullable<z.ZodString>;
+    fieldName: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodLiteral<"graphql-operation">;
+    operationName: z.ZodOptional<z.ZodString>;
+    operationType: z.ZodEnum<{
+        query: "query";
+        mutation: "mutation";
+        subscription: "subscription";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    deploymentTarget: z.ZodEnum<{
+        lambda: "lambda";
+        "ecs-task": "ecs-task";
+        container: "container";
+        "k8s-deployment": "k8s-deployment";
+    }>;
+    instanceName: z.ZodString;
+    name: z.ZodLiteral<"runtime-config">;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodLiteral<"storage-relational">;
+    storageSystem: z.ZodEnum<{
+        postgres: "postgres";
+        mysql: "mysql";
+        sqlite: "sqlite";
+    }>;
+    scope: z.ZodString;
+    table: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodLiteral<"message-bus">;
+    messageBus: z.ZodEnum<{
+        sqs: "sqs";
+        sns: "sns";
+        s3: "s3";
+        eventbridge: "eventbridge";
+        bullmq: "bullmq";
+        kafka: "kafka";
+        nats: "nats";
+    }>;
+    channel: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>], "name">;
+type Semantics = z.infer<typeof SemanticsSchema>;
+
+declare const RestSemanticsSchema: z.ZodObject<{
+    name: z.ZodLiteral<"rest">;
+    method: z.ZodNullable<z.ZodString>;
+    path: z.ZodNullable<z.ZodString>;
+    declaredResponses: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strip>;
+type RestSemantics = z.infer<typeof RestSemanticsSchema>;
+/**
+ * Normalize a route path to a canonical form for matching.
+ *
+ * - Converts Express-style params (`:id`) to brace-style (`{id}`)
+ * - Strips trailing slashes (except bare `/`)
+ * - Lowercases the static segments (params stay case-sensitive)
+ */
+declare function normalizePath(path: string): string;
+/**
+ * Whether two REST methods mean the same thing. Equal methods agree,
+ * and `"*"` agrees with any stated method, because a handler that
+ * responds to every method responds to this one. A null method was never
+ * stated, so it agrees with nothing: there is no claim to agree with.
+ *
+ * This is the counterpart of `busesAgree`. No list of methods appears
+ * here, so a wildcard pairs with whatever methods consumers write.
+ */
+declare function methodsAgree(a: string | null, b: string | null): boolean;
+/** Whether a declared route path admits a concrete request path. */
+declare function routePathAdmits(declaredPath: string, requestPath: string): boolean;
+
+/**
+ * The pairing key is `(deploymentTarget, instanceName)`, which is
+ * exactly a deployable unit, so the two fields come from
+ * `DeployableUnitSchema` instead of being written out a second time.
+ */
+declare const RuntimeConfigSemanticsSchema: z.ZodObject<{
+    deploymentTarget: z.ZodEnum<{
+        lambda: "lambda";
+        "ecs-task": "ecs-task";
+        container: "container";
+        "k8s-deployment": "k8s-deployment";
+    }>;
+    instanceName: z.ZodString;
+    name: z.ZodLiteral<"runtime-config">;
+}, z.core.$strip>;
+type RuntimeConfigSemantics = z.infer<typeof RuntimeConfigSemanticsSchema>;
+
+declare const StorageRelationalSemanticsSchema: z.ZodObject<{
+    name: z.ZodLiteral<"storage-relational">;
+    storageSystem: z.ZodEnum<{
+        postgres: "postgres";
+        mysql: "mysql";
+        sqlite: "sqlite";
+    }>;
+    scope: z.ZodString;
+    table: z.ZodString;
+}, z.core.$strip>;
+type StorageRelationalSemantics = z.infer<typeof StorageRelationalSemanticsSchema>;
+
+/**
+ * @suss/ir-core schemas: primitives shared by every suss IR.
+ *
+ * These are the types that any IR built on suss references: the
+ * structure of a value (`TypeShape`), the identity of a boundary
+ * (`BoundaryBinding` and its `Semantics` variants), where something is
+ * in the source (`SourceLocation`), and how much to trust a claim
+ * (`Confidence`). Behavioural summaries, intent docs, and later on
+ * observation records all speak in these terms, so they are defined
+ * here, in one place none of those IRs needs another IR to reach.
+ *
+ * The schemas are the single source of truth, and the package's
+ * `index.ts` derives the types from them with `z.infer`.
+ */
+
+declare const ConfidenceSourceSchema: z.ZodEnum<{
+    inferred_static: "inferred_static";
+    inferred_ai: "inferred_ai";
+    declared: "declared";
+    derived: "derived";
+}>;
+declare const ConfidenceLevelSchema: z.ZodEnum<{
+    high: "high";
+    medium: "medium";
+    low: "low";
+}>;
+/**
+ * What came of corroborating a claim by running the code
+ * (`suss corroborate`). Inputs that satisfy the claim's own conditions
+ * are generated and run through the function, and the observation
+ * either agreed every time (`observed`), disagreed at least once
+ * (`refuted`, which is either an extractor bug or a surprise, and the
+ * counterexample says which input), or never produced a verdict
+ * (`untested`, meaning no satisfying input was found, or every
+ * satisfying run hit a dependency the harness cannot supply).
+ *
+ * Corroboration adds observations to a derivation. It is extra
+ * evidence, and it never rewrites the derived claim.
+ */
+declare const CorroborationSchema: z.ZodObject<{
+    outcome: z.ZodEnum<{
+        observed: "observed";
+        refuted: "refuted";
+        untested: "untested";
+    }>;
+    runs: z.ZodNumber;
+    counterexample: z.ZodOptional<z.ZodUnknown>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const ConfidenceInfoSchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        inferred_static: "inferred_static";
+        inferred_ai: "inferred_ai";
+        declared: "declared";
+        derived: "derived";
+    }>;
+    level: z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    corroboration: z.ZodOptional<z.ZodObject<{
+        outcome: z.ZodEnum<{
+            observed: "observed";
+            refuted: "refuted";
+            untested: "untested";
+        }>;
+        runs: z.ZodNumber;
+        counterexample: z.ZodOptional<z.ZodUnknown>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const SourceLocationSchema: z.ZodObject<{
+    file: z.ZodString;
+    range: z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, z.core.$strip>;
+    exportName: z.ZodNullable<z.ZodString>;
+    workspace: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const BoundaryBindingSchema: z.ZodObject<{
+    transport: z.ZodString;
+    semantics: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        name: z.ZodLiteral<"rest">;
+        method: z.ZodNullable<z.ZodString>;
+        path: z.ZodNullable<z.ZodString>;
+        declaredResponses: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodLiteral<"function-call">;
+        module: z.ZodOptional<z.ZodString>;
+        exportName: z.ZodOptional<z.ZodString>;
+        package: z.ZodOptional<z.ZodString>;
+        exportPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodLiteral<"graphql-resolver">;
+        typeName: z.ZodNullable<z.ZodString>;
+        fieldName: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodLiteral<"graphql-operation">;
+        operationName: z.ZodOptional<z.ZodString>;
+        operationType: z.ZodEnum<{
+            query: "query";
+            mutation: "mutation";
+            subscription: "subscription";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        deploymentTarget: z.ZodEnum<{
+            lambda: "lambda";
+            "ecs-task": "ecs-task";
+            container: "container";
+            "k8s-deployment": "k8s-deployment";
+        }>;
+        instanceName: z.ZodString;
+        name: z.ZodLiteral<"runtime-config">;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodLiteral<"storage-relational">;
+        storageSystem: z.ZodEnum<{
+            postgres: "postgres";
+            mysql: "mysql";
+            sqlite: "sqlite";
+        }>;
+        scope: z.ZodString;
+        table: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodLiteral<"message-bus">;
+        messageBus: z.ZodEnum<{
+            sqs: "sqs";
+            sns: "sns";
+            s3: "s3";
+            eventbridge: "eventbridge";
+            bullmq: "bullmq";
+            kafka: "kafka";
+            nats: "nats";
+        }>;
+        channel: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>], "name">;
+    recognition: z.ZodString;
+}, z.core.$strip>;
+type TypeShape = {
+    type: "record";
+    properties: Record<string, TypeShape>;
+    spreads?: Array<{
+        sourceText: string;
+    }> | undefined;
+} | {
+    type: "dictionary";
+    values: TypeShape;
+} | {
+    type: "array";
+    items: TypeShape;
+} | {
+    type: "literal";
+    value: string | number | boolean;
+    raw?: string | undefined;
+} | {
+    type: "text";
+} | {
+    type: "integer";
+} | {
+    type: "number";
+} | {
+    type: "boolean";
+} | {
+    type: "null";
+} | {
+    type: "undefined";
+} | {
+    type: "union";
+    variants: TypeShape[];
+} | {
+    type: "ref";
+    name: string;
+    /**
+     * Where this type is written down, when it is written down
+     * anywhere. It is the key into the summary's table of definitions.
+     *
+     * A name does not identify a type. Every instantiation of one
+     * generic reports the generic's own name and file, so `Omit<User,
+     * "secret">` and `Omit<Order, "total">` are both `Omit`, and a
+     * table keyed on that gives the second one the first one's fields.
+     * This key is built from what the type actually is.
+     */
+    def?: string | undefined;
+    /**
+     * The file that declares this type, when the project declares it.
+     * Absent for a name the language or a dependency owns, which means
+     * the same thing everywhere.
+     *
+     * A name on its own does not identify a type. Two modules each
+     * declaring a `User` produce the same ref, and a checker comparing
+     * them has nothing to go on. This is what tells them apart.
+     */
+    from?: string | undefined;
+} | {
+    type: "unknown";
+};
+/**
+ * The key a table of definitions uses for the type a ref points at.
+ *
+ * A ref has the name and the file that declares it, and that pair
+ * already identifies the type, so a table keyed on it needs nothing new
+ * on the ref. A name that the language or a dependency owns has no
+ * file, and keys on the name alone.
+ */
+declare function typeDefinitionKey(ref: {
+    def?: string | undefined;
+}): string | null;
+declare const TypeShapeSchema: z.ZodType<TypeShape>;
+/**
+ * A shape with the definitions it refers to substituted back into it.
+ *
+ * Comparing two shapes means comparing their structure, and a ref has
+ * none. Rather than teach every comparison to look in a table, the
+ * definitions go back into the shape once and everything downstream
+ * reads what it always read.
+ *
+ * Substituting a definition is not a level of nesting, so it does not
+ * spend depth. Counting it meant a type six deep came back three deep,
+ * and a consumer reading a field past that was told the provider did
+ * not have it. A type that refers to itself is stopped by the names
+ * already substituted on this path, the shape walk's own cycle guard.
+ */
+declare function withDefinitionsInlined(shape: TypeShape, definitions: Record<string, TypeShape> | undefined, depth?: number, inProgress?: ReadonlySet<string>): TypeShape;
+
+export { BoundaryBindingSchema as B, ConfidenceInfoSchema as C, type DeployableUnit as D, type FunctionCallSemantics as F, type GraphqlOperationSemantics as G, type MessageBusTechnology as M, type RestSemantics as R, type Semantics as S, type TypeShape as T, ConfidenceLevelSchema as a, ConfidenceSourceSchema as b, CorroborationSchema as c, SourceLocationSchema as d, DeployableUnitSchema as e, FunctionCallSemanticsSchema as f, GraphqlOperationSemanticsSchema as g, type GraphqlResolverSemantics as h, GraphqlResolverSemanticsSchema as i, type MessageBusSemantics as j, MessageBusSemanticsSchema as k, RestSemanticsSchema as l, type RuntimeConfigSemantics as m, RuntimeConfigSemanticsSchema as n, SemanticsSchema as o, type StorageRelationalSemantics as p, StorageRelationalSemanticsSchema as q, TypeShapeSchema as r, ecsContainerInstanceName as s, methodsAgree as t, normalizePath as u, routePathAdmits as v, typeDefinitionKey as w, withDefinitionsInlined as x };