@suss/ir-core 0.1.0 → 0.2.0

package/dist/{chunk-BQEWYFCF.js → chunk-JIFTLUZX.js}

@@ -84,19 +84,19 @@ var GraphqlOperationSemanticsSchema = z.object({
   operationName: z.string().optional(),
   operationType: z.enum(["query", "mutation", "subscription"])
 });
-var RuntimeConfigSemanticsSchema = z.object({
-  name: z.literal("runtime-config"),
+var DeployableUnitSchema = z.object({
   deploymentTarget: z.enum([
     "lambda",
     "ecs-task",
     "container",
     "k8s-deployment"
   ]),
-  /**
-   * Stable identifier for the runtime instance — CFN logical resource
-   * ID for Lambda / ECS, k8s deployment name, container name.
-   */
-  instanceName: z.string()
+  // An empty name would agree with every other empty name, so a unit
+  // that names nothing has to leave the field off instead.
+  instanceName: z.string().min(1)
+});
+var RuntimeConfigSemanticsSchema = DeployableUnitSchema.extend({
+  name: z.literal("runtime-config")
 });
 var StorageRelationalSemanticsSchema = z.object({
   name: z.literal("storage-relational"),
@@ -129,6 +129,9 @@ var BoundaryBindingSchema = z.object({
   semantics: SemanticsSchema,
   recognition: z.string()
 });
+function typeDefinitionKey(ref) {
+  return ref.def ?? null;
+}
 var TypeShapeSchema = z.lazy(
   () => z.discriminatedUnion("type", [
     z.object({
@@ -153,10 +156,55 @@ var TypeShapeSchema = z.lazy(
       type: z.literal("union"),
       variants: z.array(TypeShapeSchema)
     }),
-    z.object({ type: z.literal("ref"), name: z.string() }),
+    z.object({
+      type: z.literal("ref"),
+      name: z.string(),
+      from: z.string().optional(),
+      def: z.string().optional()
+    }),
     z.object({ type: z.literal("unknown") })
   ])
 );
+var MAX_DEFINITION_DEPTH = 6;
+function withDefinitionsInlined(shape, definitions, depth = 0, inProgress = /* @__PURE__ */ new Set()) {
+  if (definitions === void 0 || depth >= MAX_DEFINITION_DEPTH) {
+    return shape;
+  }
+  const deeper = (inner) => withDefinitionsInlined(inner, definitions, depth + 1, inProgress);
+  if (shape.type === "ref") {
+    const key = typeDefinitionKey(shape);
+    if (key === null) {
+      return shape;
+    }
+    const defined = definitions[key];
+    if (defined === void 0 || inProgress.has(key)) {
+      return shape;
+    }
+    return withDefinitionsInlined(
+      defined,
+      definitions,
+      depth,
+      /* @__PURE__ */ new Set([...inProgress, key])
+    );
+  }
+  if (shape.type === "record") {
+    const properties = {};
+    for (const [name, value] of Object.entries(shape.properties)) {
+      properties[name] = deeper(value);
+    }
+    return { ...shape, properties };
+  }
+  if (shape.type === "array") {
+    return { ...shape, items: deeper(shape.items) };
+  }
+  if (shape.type === "dictionary") {
+    return { ...shape, values: deeper(shape.values) };
+  }
+  if (shape.type === "union") {
+    return { ...shape, variants: shape.variants.map(deeper) };
+  }
+  return shape;
+}
 
 export {
   ConfidenceSourceSchema,
@@ -168,10 +216,13 @@ export {
   FunctionCallSemanticsSchema,
   GraphqlResolverSemanticsSchema,
   GraphqlOperationSemanticsSchema,
+  DeployableUnitSchema,
   RuntimeConfigSemanticsSchema,
   StorageRelationalSemanticsSchema,
   MessageBusSemanticsSchema,
   SemanticsSchema,
   BoundaryBindingSchema,
-  TypeShapeSchema
+  typeDefinitionKey,
+  TypeShapeSchema,
+  withDefinitionsInlined
 };

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(index_exports, {
   ConfidenceLevelSchema: () => ConfidenceLevelSchema,
   ConfidenceSourceSchema: () => ConfidenceSourceSchema,
   CorroborationSchema: () => CorroborationSchema,
+  DeployableUnitSchema: () => DeployableUnitSchema,
   FunctionCallSemanticsSchema: () => FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema: () => GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema: () => GraphqlResolverSemanticsSchema,
@@ -42,7 +43,10 @@ __export(index_exports, {
   boundaryKey: () => boundaryKey,
   busesAgree: () => busesAgree,
   channelsPair: () => channelsPair,
+  codeScopePath: () => codeScopePath,
   countsForThreshold: () => countsForThreshold,
+  dispatchByType: () => dispatchByType,
+  fileInCodeScope: () => fileInCodeScope,
   functionCallBinding: () => functionCallBinding,
   graphqlOperationBinding: () => graphqlOperationBinding,
   graphqlResolverBinding: () => graphqlResolverBinding,
@@ -55,7 +59,9 @@ __export(index_exports, {
   ruleBoundaryMatchesKey: () => ruleBoundaryMatchesKey,
   runtimeConfigBinding: () => runtimeConfigBinding,
   storageRelationalBinding: () => storageRelationalBinding,
-  validateRule: () => validateRule
+  typeDefinitionKey: () => typeDefinitionKey,
+  validateRule: () => validateRule,
+  withDefinitionsInlined: () => withDefinitionsInlined
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -145,19 +151,19 @@ var GraphqlOperationSemanticsSchema = import_zod.z.object({
   operationName: import_zod.z.string().optional(),
   operationType: import_zod.z.enum(["query", "mutation", "subscription"])
 });
-var RuntimeConfigSemanticsSchema = import_zod.z.object({
-  name: import_zod.z.literal("runtime-config"),
+var DeployableUnitSchema = import_zod.z.object({
   deploymentTarget: import_zod.z.enum([
     "lambda",
     "ecs-task",
     "container",
     "k8s-deployment"
   ]),
-  /**
-   * Stable identifier for the runtime instance — CFN logical resource
-   * ID for Lambda / ECS, k8s deployment name, container name.
-   */
-  instanceName: import_zod.z.string()
+  // An empty name would agree with every other empty name, so a unit
+  // that names nothing has to leave the field off instead.
+  instanceName: import_zod.z.string().min(1)
+});
+var RuntimeConfigSemanticsSchema = DeployableUnitSchema.extend({
+  name: import_zod.z.literal("runtime-config")
 });
 var StorageRelationalSemanticsSchema = import_zod.z.object({
   name: import_zod.z.literal("storage-relational"),
@@ -190,6 +196,9 @@ var BoundaryBindingSchema = import_zod.z.object({
   semantics: SemanticsSchema,
   recognition: import_zod.z.string()
 });
+function typeDefinitionKey(ref) {
+  return ref.def ?? null;
+}
 var TypeShapeSchema = import_zod.z.lazy(
   () => import_zod.z.discriminatedUnion("type", [
     import_zod.z.object({
@@ -214,10 +223,55 @@ var TypeShapeSchema = import_zod.z.lazy(
       type: import_zod.z.literal("union"),
       variants: import_zod.z.array(TypeShapeSchema)
     }),
-    import_zod.z.object({ type: import_zod.z.literal("ref"), name: import_zod.z.string() }),
+    import_zod.z.object({
+      type: import_zod.z.literal("ref"),
+      name: import_zod.z.string(),
+      from: import_zod.z.string().optional(),
+      def: import_zod.z.string().optional()
+    }),
     import_zod.z.object({ type: import_zod.z.literal("unknown") })
   ])
 );
+var MAX_DEFINITION_DEPTH = 6;
+function withDefinitionsInlined(shape, definitions, depth = 0, inProgress = /* @__PURE__ */ new Set()) {
+  if (definitions === void 0 || depth >= MAX_DEFINITION_DEPTH) {
+    return shape;
+  }
+  const deeper = (inner) => withDefinitionsInlined(inner, definitions, depth + 1, inProgress);
+  if (shape.type === "ref") {
+    const key = typeDefinitionKey(shape);
+    if (key === null) {
+      return shape;
+    }
+    const defined = definitions[key];
+    if (defined === void 0 || inProgress.has(key)) {
+      return shape;
+    }
+    return withDefinitionsInlined(
+      defined,
+      definitions,
+      depth,
+      /* @__PURE__ */ new Set([...inProgress, key])
+    );
+  }
+  if (shape.type === "record") {
+    const properties = {};
+    for (const [name, value] of Object.entries(shape.properties)) {
+      properties[name] = deeper(value);
+    }
+    return { ...shape, properties };
+  }
+  if (shape.type === "array") {
+    return { ...shape, items: deeper(shape.items) };
+  }
+  if (shape.type === "dictionary") {
+    return { ...shape, values: deeper(shape.values) };
+  }
+  if (shape.type === "union") {
+    return { ...shape, variants: shape.variants.map(deeper) };
+  }
+  return shape;
+}
 
 // src/channel.ts
 function parseChannel(channel) {
@@ -259,6 +313,9 @@ function boundaryKey(binding) {
     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") {
@@ -277,6 +334,25 @@ function boundaryKey(binding) {
   return null;
 }
 
+// src/codeScope.ts
+function codeScopePath(raw) {
+  return raw.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function fileInCodeScope(file, scope) {
+  const prefix = codeScopePath(scope);
+  if (prefix === "" || prefix === ".") {
+    return true;
+  }
+  const path = codeScopePath(file);
+  return path === prefix || path.startsWith(`${prefix}/`);
+}
+
+// src/dispatch.ts
+function dispatchByType(table, value) {
+  const handler = table[value.type];
+  return handler(value);
+}
+
 // src/suppressions.ts
 var import_zod2 = require("zod");
 var SuppressionSideSchema = import_zod2.z.object({
@@ -409,10 +485,11 @@ function bodyShapesMatch(actual, declared) {
   if (actual.type === "unknown" || declared.type === "unknown") {
     return "unknown";
   }
+  if (actual.type === "ref" && declared.type === "ref") {
+    const sameDeclaration = actual.from !== void 0 && actual.from === declared.from && actual.name === declared.name;
+    return sameDeclaration ? "match" : "unknown";
+  }
   if (actual.type === "ref" || declared.type === "ref") {
-    if (actual.type === "ref" && declared.type === "ref" && actual.name === declared.name) {
-      return "match";
-    }
     return "unknown";
   }
   if (actual.type === "union") {
@@ -644,6 +721,7 @@ function messageBusBinding(opts) {
   ConfidenceLevelSchema,
   ConfidenceSourceSchema,
   CorroborationSchema,
+  DeployableUnitSchema,
   FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema,
@@ -661,7 +739,10 @@ function messageBusBinding(opts) {
   boundaryKey,
   busesAgree,
   channelsPair,
+  codeScopePath,
   countsForThreshold,
+  dispatchByType,
+  fileInCodeScope,
   functionCallBinding,
   graphqlOperationBinding,
   graphqlResolverBinding,
@@ -674,5 +755,7 @@ function messageBusBinding(opts) {
   ruleBoundaryMatchesKey,
   runtimeConfigBinding,
   storageRelationalBinding,
-  validateRule
+  typeDefinitionKey,
+  validateRule,
+  withDefinitionsInlined
 });

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { TypeShape, BoundaryBindingSchema, ConfidenceInfoSchema, ConfidenceLevelSchema, ConfidenceSourceSchema, CorroborationSchema, SemanticsSchema, SourceLocationSchema } from './schemas.cjs';
-export { FunctionCallSemanticsSchema, GraphqlOperationSemanticsSchema, GraphqlResolverSemanticsSchema, MessageBusSemanticsSchema, RestSemanticsSchema, RuntimeConfigSemanticsSchema, StorageRelationalSemanticsSchema, TypeShapeSchema } from './schemas.cjs';
+import { TypeShape, BoundaryBindingSchema, ConfidenceInfoSchema, ConfidenceLevelSchema, ConfidenceSourceSchema, CorroborationSchema, DeployableUnitSchema, SemanticsSchema, SourceLocationSchema } from './schemas.cjs';
+export { FunctionCallSemanticsSchema, GraphqlOperationSemanticsSchema, GraphqlResolverSemanticsSchema, MessageBusSemanticsSchema, RestSemanticsSchema, RuntimeConfigSemanticsSchema, StorageRelationalSemanticsSchema, TypeShapeSchema, typeDefinitionKey, withDefinitionsInlined } from './schemas.cjs';
 
 /**
  * Normalize a route path to a canonical form for matching.
@@ -14,7 +14,9 @@ declare function normalizePath(path: string): string;
  * Compute a stable string key from a boundary binding for grouping.
  * Dispatches on `semantics.name`:
  *   - `rest` → `"METHOD /normalized/path"` (null if method or path empty)
- *   - `graphql-resolver` → `"gql:<TypeName>.<fieldName>"`
+ *   - `graphql-resolver` → `"gql:<TypeName>.<fieldName>"` (null when
+ *     either is empty, which is how a resolver says the source never
+ *     named the field it answers)
  *   - `message-bus` → `"bus:<messageBus> <subject>"` (null if the
  *     subject is empty)
  *   - `function-call` → `"fn:<package>::<exportPath>"` when both
@@ -45,6 +47,34 @@ declare function busesAgree(a: string | null, b: string | null): boolean;
 /** Whether two channels name the same subject on agreeing buses. */
 declare function channelsPair(a: string, b: string): boolean;
 
+/**
+ * The canonical form of a code-scope directory: no leading `./`, no
+ * trailing slash, no surrounding whitespace. An empty result means the
+ * scope names the project root.
+ */
+declare function codeScopePath(raw: string): string;
+/**
+ * Whether a project-relative file sits inside a code scope. Matching
+ * stops at a segment boundary, so `src/foo` covers `src/foo/a.ts` and
+ * never `src/foobar/a.ts`. A scope naming the project root covers
+ * every file.
+ *
+ * Both arguments pass through `codeScopePath`, so a scope stored under
+ * either of the older trailing-slash conventions still reads correctly.
+ */
+declare function fileInCodeScope(file: string, scope: string): boolean;
+
+type DispatchTable<T extends {
+    type: string;
+}, R> = {
+    [K in T["type"]]: (variant: Extract<T, {
+        type: K;
+    }>) => R;
+};
+declare function dispatchByType<T extends {
+    type: string;
+}, R>(table: DispatchTable<T, R>, value: T): R;
+
 declare const SuppressionRuleSchema: z.ZodObject<{
     kind: z.ZodOptional<z.ZodString>;
     boundary: z.ZodOptional<z.ZodString>;
@@ -204,6 +234,7 @@ type StorageRelationalSemantics = Extract<Semantics, {
 type MessageBusSemantics = Extract<Semantics, {
     name: "message-bus";
 }>;
+type DeployableUnit = z.infer<typeof DeployableUnitSchema>;
 
 /**
  * Build a REST-semantics binding. `method` and `path` can be empty
@@ -293,4 +324,4 @@ declare function messageBusBinding(opts: {
     channel: string;
 }): BoundaryBinding;
 
-export { type BoundaryBinding, BoundaryBindingSchema, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, type FindingSuppression, type FunctionCallSemantics, type GraphqlOperationSemantics, type GraphqlResolverSemantics, type MatchResult, type MessageBusSemantics, type ParsedChannel, type RestSemantics, type RuntimeConfigSemantics, type Semantics, SemanticsSchema, type SourceLocation, SourceLocationSchema, type StorageRelationalSemantics, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, busesAgree, channelsPair, countsForThreshold, functionCallBinding, graphqlOperationBinding, graphqlResolverBinding, messageBusBinding, normalizePath, normalizeRuleBoundary, packageExportBinding, parseChannel, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, storageRelationalBinding, validateRule };
+export { type BoundaryBinding, BoundaryBindingSchema, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, type DeployableUnit, DeployableUnitSchema, type DispatchTable, type FindingSuppression, type FunctionCallSemantics, type GraphqlOperationSemantics, type GraphqlResolverSemantics, type MatchResult, type MessageBusSemantics, type ParsedChannel, type RestSemantics, type RuntimeConfigSemantics, type Semantics, SemanticsSchema, type SourceLocation, SourceLocationSchema, type StorageRelationalSemantics, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, busesAgree, channelsPair, codeScopePath, countsForThreshold, dispatchByType, fileInCodeScope, functionCallBinding, graphqlOperationBinding, graphqlResolverBinding, messageBusBinding, normalizePath, normalizeRuleBoundary, packageExportBinding, parseChannel, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, storageRelationalBinding, validateRule };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { TypeShape, BoundaryBindingSchema, ConfidenceInfoSchema, ConfidenceLevelSchema, ConfidenceSourceSchema, CorroborationSchema, SemanticsSchema, SourceLocationSchema } from './schemas.js';
-export { FunctionCallSemanticsSchema, GraphqlOperationSemanticsSchema, GraphqlResolverSemanticsSchema, MessageBusSemanticsSchema, RestSemanticsSchema, RuntimeConfigSemanticsSchema, StorageRelationalSemanticsSchema, TypeShapeSchema } from './schemas.js';
+import { TypeShape, BoundaryBindingSchema, ConfidenceInfoSchema, ConfidenceLevelSchema, ConfidenceSourceSchema, CorroborationSchema, DeployableUnitSchema, SemanticsSchema, SourceLocationSchema } from './schemas.js';
+export { FunctionCallSemanticsSchema, GraphqlOperationSemanticsSchema, GraphqlResolverSemanticsSchema, MessageBusSemanticsSchema, RestSemanticsSchema, RuntimeConfigSemanticsSchema, StorageRelationalSemanticsSchema, TypeShapeSchema, typeDefinitionKey, withDefinitionsInlined } from './schemas.js';
 
 /**
  * Normalize a route path to a canonical form for matching.
@@ -14,7 +14,9 @@ declare function normalizePath(path: string): string;
  * Compute a stable string key from a boundary binding for grouping.
  * Dispatches on `semantics.name`:
  *   - `rest` → `"METHOD /normalized/path"` (null if method or path empty)
- *   - `graphql-resolver` → `"gql:<TypeName>.<fieldName>"`
+ *   - `graphql-resolver` → `"gql:<TypeName>.<fieldName>"` (null when
+ *     either is empty, which is how a resolver says the source never
+ *     named the field it answers)
  *   - `message-bus` → `"bus:<messageBus> <subject>"` (null if the
  *     subject is empty)
  *   - `function-call` → `"fn:<package>::<exportPath>"` when both
@@ -45,6 +47,34 @@ declare function busesAgree(a: string | null, b: string | null): boolean;
 /** Whether two channels name the same subject on agreeing buses. */
 declare function channelsPair(a: string, b: string): boolean;
 
+/**
+ * The canonical form of a code-scope directory: no leading `./`, no
+ * trailing slash, no surrounding whitespace. An empty result means the
+ * scope names the project root.
+ */
+declare function codeScopePath(raw: string): string;
+/**
+ * Whether a project-relative file sits inside a code scope. Matching
+ * stops at a segment boundary, so `src/foo` covers `src/foo/a.ts` and
+ * never `src/foobar/a.ts`. A scope naming the project root covers
+ * every file.
+ *
+ * Both arguments pass through `codeScopePath`, so a scope stored under
+ * either of the older trailing-slash conventions still reads correctly.
+ */
+declare function fileInCodeScope(file: string, scope: string): boolean;
+
+type DispatchTable<T extends {
+    type: string;
+}, R> = {
+    [K in T["type"]]: (variant: Extract<T, {
+        type: K;
+    }>) => R;
+};
+declare function dispatchByType<T extends {
+    type: string;
+}, R>(table: DispatchTable<T, R>, value: T): R;
+
 declare const SuppressionRuleSchema: z.ZodObject<{
     kind: z.ZodOptional<z.ZodString>;
     boundary: z.ZodOptional<z.ZodString>;
@@ -204,6 +234,7 @@ type StorageRelationalSemantics = Extract<Semantics, {
 type MessageBusSemantics = Extract<Semantics, {
     name: "message-bus";
 }>;
+type DeployableUnit = z.infer<typeof DeployableUnitSchema>;
 
 /**
  * Build a REST-semantics binding. `method` and `path` can be empty
@@ -293,4 +324,4 @@ declare function messageBusBinding(opts: {
     channel: string;
 }): BoundaryBinding;
 
-export { type BoundaryBinding, BoundaryBindingSchema, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, type FindingSuppression, type FunctionCallSemantics, type GraphqlOperationSemantics, type GraphqlResolverSemantics, type MatchResult, type MessageBusSemantics, type ParsedChannel, type RestSemantics, type RuntimeConfigSemantics, type Semantics, SemanticsSchema, type SourceLocation, SourceLocationSchema, type StorageRelationalSemantics, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, busesAgree, channelsPair, countsForThreshold, functionCallBinding, graphqlOperationBinding, graphqlResolverBinding, messageBusBinding, normalizePath, normalizeRuleBoundary, packageExportBinding, parseChannel, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, storageRelationalBinding, validateRule };
+export { type BoundaryBinding, BoundaryBindingSchema, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, type DeployableUnit, DeployableUnitSchema, type DispatchTable, type FindingSuppression, type FunctionCallSemantics, type GraphqlOperationSemantics, type GraphqlResolverSemantics, type MatchResult, type MessageBusSemantics, type ParsedChannel, type RestSemantics, type RuntimeConfigSemantics, type Semantics, SemanticsSchema, type SourceLocation, SourceLocationSchema, type StorageRelationalSemantics, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, busesAgree, channelsPair, codeScopePath, countsForThreshold, dispatchByType, fileInCodeScope, functionCallBinding, graphqlOperationBinding, graphqlResolverBinding, messageBusBinding, normalizePath, normalizeRuleBoundary, packageExportBinding, parseChannel, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, storageRelationalBinding, validateRule };

package/dist/index.js

@@ -4,6 +4,7 @@ import {
   ConfidenceLevelSchema,
   ConfidenceSourceSchema,
   CorroborationSchema,
+  DeployableUnitSchema,
   FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema,
@@ -13,8 +14,10 @@ import {
   SemanticsSchema,
   SourceLocationSchema,
   StorageRelationalSemanticsSchema,
-  TypeShapeSchema
-} from "./chunk-BQEWYFCF.js";
+  TypeShapeSchema,
+  typeDefinitionKey,
+  withDefinitionsInlined
+} from "./chunk-JIFTLUZX.js";
 
 // src/channel.ts
 function parseChannel(channel) {
@@ -56,6 +59,9 @@ function boundaryKey(binding) {
     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") {
@@ -74,6 +80,25 @@ function boundaryKey(binding) {
   return null;
 }
 
+// src/codeScope.ts
+function codeScopePath(raw) {
+  return raw.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function fileInCodeScope(file, scope) {
+  const prefix = codeScopePath(scope);
+  if (prefix === "" || prefix === ".") {
+    return true;
+  }
+  const path = codeScopePath(file);
+  return path === prefix || path.startsWith(`${prefix}/`);
+}
+
+// src/dispatch.ts
+function dispatchByType(table, value) {
+  const handler = table[value.type];
+  return handler(value);
+}
+
 // src/suppressions.ts
 import { z } from "zod";
 var SuppressionSideSchema = z.object({
@@ -206,10 +231,11 @@ function bodyShapesMatch(actual, declared) {
   if (actual.type === "unknown" || declared.type === "unknown") {
     return "unknown";
   }
+  if (actual.type === "ref" && declared.type === "ref") {
+    const sameDeclaration = actual.from !== void 0 && actual.from === declared.from && actual.name === declared.name;
+    return sameDeclaration ? "match" : "unknown";
+  }
   if (actual.type === "ref" || declared.type === "ref") {
-    if (actual.type === "ref" && declared.type === "ref" && actual.name === declared.name) {
-      return "match";
-    }
     return "unknown";
   }
   if (actual.type === "union") {
@@ -440,6 +466,7 @@ export {
   ConfidenceLevelSchema,
   ConfidenceSourceSchema,
   CorroborationSchema,
+  DeployableUnitSchema,
   FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema,
@@ -457,7 +484,10 @@ export {
   boundaryKey,
   busesAgree,
   channelsPair,
+  codeScopePath,
   countsForThreshold,
+  dispatchByType,
+  fileInCodeScope,
   functionCallBinding,
   graphqlOperationBinding,
   graphqlResolverBinding,
@@ -470,5 +500,7 @@ export {
   ruleBoundaryMatchesKey,
   runtimeConfigBinding,
   storageRelationalBinding,
-  validateRule
+  typeDefinitionKey,
+  validateRule,
+  withDefinitionsInlined
 };

package/dist/schemas.cjs

@@ -25,6 +25,7 @@ __export(schemas_exports, {
   ConfidenceLevelSchema: () => ConfidenceLevelSchema,
   ConfidenceSourceSchema: () => ConfidenceSourceSchema,
   CorroborationSchema: () => CorroborationSchema,
+  DeployableUnitSchema: () => DeployableUnitSchema,
   FunctionCallSemanticsSchema: () => FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema: () => GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema: () => GraphqlResolverSemanticsSchema,
@@ -34,7 +35,9 @@ __export(schemas_exports, {
   SemanticsSchema: () => SemanticsSchema,
   SourceLocationSchema: () => SourceLocationSchema,
   StorageRelationalSemanticsSchema: () => StorageRelationalSemanticsSchema,
-  TypeShapeSchema: () => TypeShapeSchema
+  TypeShapeSchema: () => TypeShapeSchema,
+  typeDefinitionKey: () => typeDefinitionKey,
+  withDefinitionsInlined: () => withDefinitionsInlined
 });
 module.exports = __toCommonJS(schemas_exports);
 var import_zod = require("zod");
@@ -122,19 +125,19 @@ var GraphqlOperationSemanticsSchema = import_zod.z.object({
   operationName: import_zod.z.string().optional(),
   operationType: import_zod.z.enum(["query", "mutation", "subscription"])
 });
-var RuntimeConfigSemanticsSchema = import_zod.z.object({
-  name: import_zod.z.literal("runtime-config"),
+var DeployableUnitSchema = import_zod.z.object({
   deploymentTarget: import_zod.z.enum([
     "lambda",
     "ecs-task",
     "container",
     "k8s-deployment"
   ]),
-  /**
-   * Stable identifier for the runtime instance — CFN logical resource
-   * ID for Lambda / ECS, k8s deployment name, container name.
-   */
-  instanceName: import_zod.z.string()
+  // An empty name would agree with every other empty name, so a unit
+  // that names nothing has to leave the field off instead.
+  instanceName: import_zod.z.string().min(1)
+});
+var RuntimeConfigSemanticsSchema = DeployableUnitSchema.extend({
+  name: import_zod.z.literal("runtime-config")
 });
 var StorageRelationalSemanticsSchema = import_zod.z.object({
   name: import_zod.z.literal("storage-relational"),
@@ -167,6 +170,9 @@ var BoundaryBindingSchema = import_zod.z.object({
   semantics: SemanticsSchema,
   recognition: import_zod.z.string()
 });
+function typeDefinitionKey(ref) {
+  return ref.def ?? null;
+}
 var TypeShapeSchema = import_zod.z.lazy(
   () => import_zod.z.discriminatedUnion("type", [
     import_zod.z.object({
@@ -191,10 +197,55 @@ var TypeShapeSchema = import_zod.z.lazy(
       type: import_zod.z.literal("union"),
       variants: import_zod.z.array(TypeShapeSchema)
     }),
-    import_zod.z.object({ type: import_zod.z.literal("ref"), name: import_zod.z.string() }),
+    import_zod.z.object({
+      type: import_zod.z.literal("ref"),
+      name: import_zod.z.string(),
+      from: import_zod.z.string().optional(),
+      def: import_zod.z.string().optional()
+    }),
     import_zod.z.object({ type: import_zod.z.literal("unknown") })
   ])
 );
+var MAX_DEFINITION_DEPTH = 6;
+function withDefinitionsInlined(shape, definitions, depth = 0, inProgress = /* @__PURE__ */ new Set()) {
+  if (definitions === void 0 || depth >= MAX_DEFINITION_DEPTH) {
+    return shape;
+  }
+  const deeper = (inner) => withDefinitionsInlined(inner, definitions, depth + 1, inProgress);
+  if (shape.type === "ref") {
+    const key = typeDefinitionKey(shape);
+    if (key === null) {
+      return shape;
+    }
+    const defined = definitions[key];
+    if (defined === void 0 || inProgress.has(key)) {
+      return shape;
+    }
+    return withDefinitionsInlined(
+      defined,
+      definitions,
+      depth,
+      /* @__PURE__ */ new Set([...inProgress, key])
+    );
+  }
+  if (shape.type === "record") {
+    const properties = {};
+    for (const [name, value] of Object.entries(shape.properties)) {
+      properties[name] = deeper(value);
+    }
+    return { ...shape, properties };
+  }
+  if (shape.type === "array") {
+    return { ...shape, items: deeper(shape.items) };
+  }
+  if (shape.type === "dictionary") {
+    return { ...shape, values: deeper(shape.values) };
+  }
+  if (shape.type === "union") {
+    return { ...shape, variants: shape.variants.map(deeper) };
+  }
+  return shape;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BoundaryBindingSchema,
@@ -202,6 +253,7 @@ var TypeShapeSchema = import_zod.z.lazy(
   ConfidenceLevelSchema,
   ConfidenceSourceSchema,
   CorroborationSchema,
+  DeployableUnitSchema,
   FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema,
@@ -211,5 +263,7 @@ var TypeShapeSchema = import_zod.z.lazy(
   SemanticsSchema,
   SourceLocationSchema,
   StorageRelationalSemanticsSchema,
-  TypeShapeSchema
+  TypeShapeSchema,
+  typeDefinitionKey,
+  withDefinitionsInlined
 });

package/dist/schemas.d.cts

@@ -101,13 +101,32 @@ declare const GraphqlOperationSemanticsSchema: z.ZodObject<{
     }>;
 }, z.core.$strip>;
 /**
- * Provider-side runtime configuration channel — env vars + their
+ * One thing that gets deployed and runs on its own: a Lambda
+ * function, an ECS task's container, a plain container, 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>;
+/**
+ * Provider-side runtime configuration channel: env vars and their
  * declared values on a deployable unit. The channel is the boundary;
  * env var names are FIELDS on its contract. Pairing key:
- * `(deploymentTarget, instanceName)`.
+ * `(deploymentTarget, instanceName)`, which is exactly a deployable
+ * unit, so the two fields come from `DeployableUnitSchema` rather
+ * than being spelled a second time.
  */
 declare const RuntimeConfigSemanticsSchema: z.ZodObject<{
-    name: z.ZodLiteral<"runtime-config">;
     deploymentTarget: z.ZodEnum<{
         lambda: "lambda";
         "ecs-task": "ecs-task";
@@ -115,6 +134,7 @@ declare const RuntimeConfigSemanticsSchema: z.ZodObject<{
         "k8s-deployment": "k8s-deployment";
     }>;
     instanceName: z.ZodString;
+    name: z.ZodLiteral<"runtime-config">;
 }, z.core.$strip>;
 /**
  * Provider-side relational storage table. Columns are FIELDS on the
@@ -179,7 +199,6 @@ declare const SemanticsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         subscription: "subscription";
     }>;
 }, z.core.$strip>, z.ZodObject<{
-    name: z.ZodLiteral<"runtime-config">;
     deploymentTarget: z.ZodEnum<{
         lambda: "lambda";
         "ecs-task": "ecs-task";
@@ -187,6 +206,7 @@ declare const SemanticsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         "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<{
@@ -233,7 +253,6 @@ declare const BoundaryBindingSchema: z.ZodObject<{
             subscription: "subscription";
         }>;
     }, z.core.$strip>, z.ZodObject<{
-        name: z.ZodLiteral<"runtime-config">;
         deploymentTarget: z.ZodEnum<{
             lambda: "lambda";
             "ecs-task": "ecs-task";
@@ -241,6 +260,7 @@ declare const BoundaryBindingSchema: z.ZodObject<{
             "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<{
@@ -297,9 +317,57 @@ type TypeShape = {
 } | {
     type: "ref";
     name: string;
+    /**
+     * Where this type is written down, when 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 hands the second one the first one's
+     * fields. This 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";
 };
+/**
+ * How a table of definitions names the type a ref points at.
+ *
+ * A ref carries 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 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 names put 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
+ * table goes back into the shape once, and everything downstream reads
+ * what it always read.
+ *
+ * Putting a definition back is a substitution rather than a level of
+ * nesting, so it does not spend depth. Counting it did: a type six
+ * deep came back three deep, and a consumer reading a field past that
+ * point was told the provider did not have it. What stops a type that
+ * names itself is the set of names already being put back on this
+ * path, which is how the shape walk guards its own cycles.
+ */
+declare function withDefinitionsInlined(shape: TypeShape, definitions: Record<string, TypeShape> | undefined, depth?: number, inProgress?: ReadonlySet<string>): TypeShape;
 
-export { BoundaryBindingSchema, ConfidenceInfoSchema, ConfidenceLevelSchema, ConfidenceSourceSchema, CorroborationSchema, FunctionCallSemanticsSchema, GraphqlOperationSemanticsSchema, GraphqlResolverSemanticsSchema, MessageBusSemanticsSchema, RestSemanticsSchema, RuntimeConfigSemanticsSchema, SemanticsSchema, SourceLocationSchema, StorageRelationalSemanticsSchema, type TypeShape, TypeShapeSchema };
+export { BoundaryBindingSchema, ConfidenceInfoSchema, ConfidenceLevelSchema, ConfidenceSourceSchema, CorroborationSchema, DeployableUnitSchema, FunctionCallSemanticsSchema, GraphqlOperationSemanticsSchema, GraphqlResolverSemanticsSchema, MessageBusSemanticsSchema, RestSemanticsSchema, RuntimeConfigSemanticsSchema, SemanticsSchema, SourceLocationSchema, StorageRelationalSemanticsSchema, type TypeShape, TypeShapeSchema, typeDefinitionKey, withDefinitionsInlined };

package/dist/schemas.d.ts

@@ -101,13 +101,32 @@ declare const GraphqlOperationSemanticsSchema: z.ZodObject<{
     }>;
 }, z.core.$strip>;
 /**
- * Provider-side runtime configuration channel — env vars + their
+ * One thing that gets deployed and runs on its own: a Lambda
+ * function, an ECS task's container, a plain container, 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>;
+/**
+ * Provider-side runtime configuration channel: env vars and their
  * declared values on a deployable unit. The channel is the boundary;
  * env var names are FIELDS on its contract. Pairing key:
- * `(deploymentTarget, instanceName)`.
+ * `(deploymentTarget, instanceName)`, which is exactly a deployable
+ * unit, so the two fields come from `DeployableUnitSchema` rather
+ * than being spelled a second time.
  */
 declare const RuntimeConfigSemanticsSchema: z.ZodObject<{
-    name: z.ZodLiteral<"runtime-config">;
     deploymentTarget: z.ZodEnum<{
         lambda: "lambda";
         "ecs-task": "ecs-task";
@@ -115,6 +134,7 @@ declare const RuntimeConfigSemanticsSchema: z.ZodObject<{
         "k8s-deployment": "k8s-deployment";
     }>;
     instanceName: z.ZodString;
+    name: z.ZodLiteral<"runtime-config">;
 }, z.core.$strip>;
 /**
  * Provider-side relational storage table. Columns are FIELDS on the
@@ -179,7 +199,6 @@ declare const SemanticsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         subscription: "subscription";
     }>;
 }, z.core.$strip>, z.ZodObject<{
-    name: z.ZodLiteral<"runtime-config">;
     deploymentTarget: z.ZodEnum<{
         lambda: "lambda";
         "ecs-task": "ecs-task";
@@ -187,6 +206,7 @@ declare const SemanticsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         "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<{
@@ -233,7 +253,6 @@ declare const BoundaryBindingSchema: z.ZodObject<{
             subscription: "subscription";
         }>;
     }, z.core.$strip>, z.ZodObject<{
-        name: z.ZodLiteral<"runtime-config">;
         deploymentTarget: z.ZodEnum<{
             lambda: "lambda";
             "ecs-task": "ecs-task";
@@ -241,6 +260,7 @@ declare const BoundaryBindingSchema: z.ZodObject<{
             "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<{
@@ -297,9 +317,57 @@ type TypeShape = {
 } | {
     type: "ref";
     name: string;
+    /**
+     * Where this type is written down, when 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 hands the second one the first one's
+     * fields. This 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";
 };
+/**
+ * How a table of definitions names the type a ref points at.
+ *
+ * A ref carries 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 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 names put 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
+ * table goes back into the shape once, and everything downstream reads
+ * what it always read.
+ *
+ * Putting a definition back is a substitution rather than a level of
+ * nesting, so it does not spend depth. Counting it did: a type six
+ * deep came back three deep, and a consumer reading a field past that
+ * point was told the provider did not have it. What stops a type that
+ * names itself is the set of names already being put back on this
+ * path, which is how the shape walk guards its own cycles.
+ */
+declare function withDefinitionsInlined(shape: TypeShape, definitions: Record<string, TypeShape> | undefined, depth?: number, inProgress?: ReadonlySet<string>): TypeShape;
 
-export { BoundaryBindingSchema, ConfidenceInfoSchema, ConfidenceLevelSchema, ConfidenceSourceSchema, CorroborationSchema, FunctionCallSemanticsSchema, GraphqlOperationSemanticsSchema, GraphqlResolverSemanticsSchema, MessageBusSemanticsSchema, RestSemanticsSchema, RuntimeConfigSemanticsSchema, SemanticsSchema, SourceLocationSchema, StorageRelationalSemanticsSchema, type TypeShape, TypeShapeSchema };
+export { BoundaryBindingSchema, ConfidenceInfoSchema, ConfidenceLevelSchema, ConfidenceSourceSchema, CorroborationSchema, DeployableUnitSchema, FunctionCallSemanticsSchema, GraphqlOperationSemanticsSchema, GraphqlResolverSemanticsSchema, MessageBusSemanticsSchema, RestSemanticsSchema, RuntimeConfigSemanticsSchema, SemanticsSchema, SourceLocationSchema, StorageRelationalSemanticsSchema, type TypeShape, TypeShapeSchema, typeDefinitionKey, withDefinitionsInlined };

package/dist/schemas.js

@@ -4,6 +4,7 @@ import {
   ConfidenceLevelSchema,
   ConfidenceSourceSchema,
   CorroborationSchema,
+  DeployableUnitSchema,
   FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema,
@@ -13,14 +14,17 @@ import {
   SemanticsSchema,
   SourceLocationSchema,
   StorageRelationalSemanticsSchema,
-  TypeShapeSchema
-} from "./chunk-BQEWYFCF.js";
+  TypeShapeSchema,
+  typeDefinitionKey,
+  withDefinitionsInlined
+} from "./chunk-JIFTLUZX.js";
 export {
   BoundaryBindingSchema,
   ConfidenceInfoSchema,
   ConfidenceLevelSchema,
   ConfidenceSourceSchema,
   CorroborationSchema,
+  DeployableUnitSchema,
   FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema,
@@ -30,5 +34,7 @@ export {
   SemanticsSchema,
   SourceLocationSchema,
   StorageRelationalSemanticsSchema,
-  TypeShapeSchema
+  TypeShapeSchema,
+  typeDefinitionKey,
+  withDefinitionsInlined
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/ir-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Shared IR primitives for suss — type shapes, boundary bindings, source locations, and confidence. Imported by both @suss/behavioral-ir and @suss/intent-ir so neither depends on the other.",
   "keywords": [