@suss/contract-aws-apigateway 0.33.0 → 0.34.0

package/README.md

@@ -1,14 +1,14 @@
 # @suss/contract-aws-apigateway
 
-Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and says where the two disagree.
+Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and reports where the two disagree.
 
-Generate suss `BehavioralSummary[]` for AWS API Gateway resources (REST + HTTP API), independent of how they were deployed.
+This package builds suss `BehavioralSummary[]` for AWS API Gateway resources (REST and HTTP API), however they were deployed.
 
 ## What this package is
 
-`@suss/contract-aws-apigateway` is a **resource-semantics stub**: given a normalized configuration, it knows what an API Gateway endpoint *does* (status codes, authorizer behavior, CORS preflight, throttling). It does **not** know how someone wrote that configuration; a manifest reader does that job (`@suss/contract-cloudformation`, future CDK/Terraform readers), parsing its source format and handing a normalized config to this package.
+`@suss/contract-aws-apigateway` is a **resource-semantics stub**. Given a normalized configuration, it works out what an API Gateway endpoint *does*: its status codes, authorizer behavior, CORS preflight and throttling. It does **not** read the configuration as someone wrote it. A manifest reader does that: `@suss/contract-cloudformation` today, and `@suss/contract-serverless` through it. The reader parses its own source format and passes a normalized config to this package. `@suss/contract-terraform` exists, but it does not read API Gateway resources yet, and there is no CDK reader.
 
-This separation means: configure your API in CloudFormation, CDK, SAM, or Terraform, and the same resource semantics produce the same summary.
+Because of that split, an API configured in CloudFormation, SAM or a `serverless.yml` gets the same resource semantics and the same summary. A CDK or Terraform reader would pass its config to the same code.
 
 ## Where it fits
 
@@ -17,15 +17,16 @@ packages/contract/
   openapi/              # Spec → summaries (declares what the API claims to be)
   aws-apigateway/       # Resource semantics: what AWS API Gateway actually does
   cloudformation/       # Manifest reader: walks CFN/SAM, builds configs, delegates here
+  serverless/           # Rewrites serverless.yml as SAM and hands it to cloudformation/
+  terraform/            # Reads Terraform; does not read API Gateway resources yet
   (future) cdk-synth/   # Same delegation pattern
-  (future) terraform/   # Same delegation pattern
 ```
 
 ## Why configuration matters
 
-A handler that only returns `200` produces a *much* larger behavioral envelope once it's deployed behind API Gateway: an authorizer adds `401`/`403`, request validation adds `400`, throttling adds `429`, integration timeouts add `504`, CORS adds an `OPTIONS` preflight endpoint. Without modeling these, a consumer that handles `429` looks like it has a dead branch, when in reality the platform produces `429` even though the handler doesn't.
+A handler that only returns `200` can respond in *many* more ways once it is deployed behind API Gateway. An authorizer adds `401`/`403`, request validation adds `400`, throttling adds `429`, integration timeouts add `504`, and CORS adds an `OPTIONS` preflight endpoint. If suss did not model these, a consumer that handles `429` would look like it had a dead branch, when the platform does produce `429` even though the handler never does.
 
-These transitions are emitted with `confidence.source: "derived"` and an opaque `Predicate` of the form `platform:apiGateway:<contract>`. Each transition's `metadata` records where the transition came from (which configuration field introduced it) for `inspect`/`diff` output, so consumers do not have to work out the platform cause themselves.
+These transitions come out with `confidence.source: "derived"` and an opaque `Predicate` of the form `platform:apiGateway:<contract>`. Each transition's `metadata` records which configuration field introduced it, for `inspect`/`diff` output, so consumers do not have to work out the platform cause themselves.
 
 ## More
 

package/dist/index.cjs

@@ -317,10 +317,6 @@ function buildRouteSummary(route, parsed, api, sourceFile) {
             statusCode
           }))
         },
-        // Additive pointer to the code that implements this route (SAM
-        // Lambda proxy Handler), so a checker can correlate the declared
-        // route with the extracted handler summary carrying the same
-        // REST binding.
         ...route.implementingHandler !== void 0 ? { implementingHandler: route.implementingHandler } : {}
       }
     )
@@ -483,13 +479,9 @@ function buildEndpointSummary(endpoint, api, sourceFile) {
         integrationType: endpoint.integration.type
       },
       {
-        // The integration's declared status codes (from MethodResponses
-        // in the CFN template) are the declared contract here.
-        // Platform-injected transitions (authorizer 401/403, throttle
-        // 429, etc.) come from SEPARATE config fields and so are
-        // independent from this contract: contract-consistency
-        // comparison is meaningful and will surface template-internal
-        // inconsistencies.
+        // The platform's responses come from other settings than
+        // MethodResponses, so comparing them with this contract can find
+        // a template that contradicts itself.
         declaredContract: {
           framework: FRAMEWORK,
           provenance: "independent",
@@ -497,10 +489,6 @@ function buildEndpointSummary(endpoint, api, sourceFile) {
             statusCode
           }))
         },
-        // Additive pointer to the code that implements this endpoint
-        // (SAM Lambda proxy Handler), so a checker can correlate the
-        // declared route with the extracted handler summary carrying the
-        // same REST binding.
         ...endpoint.implementingHandler !== void 0 ? { implementingHandler: endpoint.implementingHandler } : {}
       }
     )

package/dist/index.d.cts

@@ -1,11 +1,18 @@
 import { BehavioralSummary } from '@suss/behavioral-ir';
 
 /**
- * Reference back into the source manifest that introduced a piece of
- * configuration. Carried in `Transition.metadata.configRef` so inspect/
- * diff can attribute platform-injected transitions to the file + path
- * where the user authored them. Always emit an absolute file path; the
- * pointer is a JSON-Pointer-ish hint, intentionally not validated.
+ * The configuration a manifest reader builds and passes to
+ * restApiToSummaries or httpApiToSummaries, whatever format it read.
+ *
+ * Besides routes, it includes the settings that change behavior:
+ * authorizers, CORS, throttling and request validation. Each one adds
+ * responses the platform returns that no handler code shows.
+ */
+/**
+ * Where in the source manifest a piece of configuration was written.
+ * Inspect and diff use it to point a platform-added response at the line
+ * that caused it. The file is always absolute, and the pointer is a hint
+ * in the style of a JSON Pointer that nothing validates.
  */
 interface ConfigRef {
     /** Absolute path to the source manifest file. */
@@ -14,20 +21,18 @@ interface ConfigRef {
     pointer: string;
 }
 /**
- * One of the well-known platform contracts that produce extra response
- * transitions. Used as the `cause` token in opaque predicates and as a
- * key for collapsing per-status transitions. Closed enum so the checker
- * and renderers can switch on it.
+ * The platform behaviors that add responses. Each value is the `cause` in
+ * a platform transition's metadata, and every cause that lands on one
+ * status code is merged into a single transition.
  */
 type PlatformCause = "authorization" | "api-key" | "request-validation" | "throttle" | "integration-timeout" | "integration-failure" | "cors-preflight";
 type AuthorizerType = "iam" | "cognito" | "lambda-token" | "lambda-request" | "jwt";
 interface AuthorizerConfig {
     type: AuthorizerType;
     /**
-     * When true, missing/invalid credentials produce 401; authenticated
-     * but denied produces 403. When false, the authorizer is configured
-     * but anonymous calls bypass it (mostly relevant for public-fallback
-     * IAM and Lambda authorizers with caching off).
+     * When true or unset, missing or invalid credentials return 401 and a
+     * denied caller gets 403. When false, anonymous calls pass the
+     * authorizer, so only 403 is added.
      */
     identitySourceRequired?: boolean;
     configRef?: ConfigRef;
@@ -53,22 +58,20 @@ interface RequestValidationConfig {
     configRef?: ConfigRef;
 }
 /**
- * Pointer from a declared route to the code that implements it. A
- * manifest reader (CFN/SAM, CDK, Terraform) fills this in when it knows
- * which module + export backs the route, e.g. a SAM Lambda proxy
- * integration whose `Handler` gives the file and export. The fields are
- * generic "where is the code" identity, not any one manifest's
- * semantics; `aws-apigateway` puts the pointer onto the summary
- * (`metadata.http.implementingHandler`) without interpreting it, so a
- * checker can later correlate the declared route with the extracted
- * handler summary with the same REST binding.
+ * The code that implements a declared route. A manifest reader fills it
+ * in when it can tell which module and export serve the route, as with a
+ * SAM Lambda proxy integration whose `Handler` gives both.
+ *
+ * This package copies it to `metadata.http.implementingHandler` without
+ * reading it, so the checker can match the declared route to the handler
+ * summary extracted from that code.
  */
 interface HandlerPointer {
     /** Raw handler reference, e.g. "src/handlers/confirmToken.handler". */
     handler: string;
     /** Module-path portion (before the final dot), e.g. "src/handlers/confirmToken". */
     modulePath: string;
-    /** Exported symbol the handler names, e.g. "handler". */
+    /** The exported function, e.g. "handler". */
     exportName: string;
     /** Base directory the module path resolves against (SAM CodeUri). */
     codeUri?: string;
@@ -77,28 +80,24 @@ interface HandlerPointer {
 }
 type IntegrationType = "lambda" | "lambda-proxy" | "http" | "http-proxy" | "mock" | "aws-service" | "vpc-link"
 /**
- * The manifest declared an endpoint but didn't specify the integration
- * type. We can't claim 502/504 will fire without knowing what's behind
- * the route, so platform-failure transitions are suppressed for this
- * type. Used by manifest readers as a fallback rather than fabricating
- * a guessed integration.
+ * The manifest declared an endpoint without an integration type. A
+ * reader uses this in place of a guess, and no 502 or 504 is added,
+ * because nothing is known about the backend.
  */
  | "unknown";
 interface IntegrationConfig {
     type: IntegrationType;
     /**
-     * Status codes the backend integration can produce. For proxy
-     * integrations this is what the handler emits; for non-proxy it's
-     * what `IntegrationResponses` map to. Empty array is allowed and
-     * means "we don't know", only platform-injected transitions will
-     * be emitted.
+     * Status codes the backend can return: what the handler returns for a
+     * proxy integration, or what `IntegrationResponses` map to otherwise.
+     * An empty array means they are unknown, and only the platform's
+     * responses are emitted.
      */
     statusCodes: number[];
     /**
-     * REST API Gateway hard cap is 29s; HTTP API is 30s. When set,
-     * a synthetic 504 is added if the integration could exceed it.
-     * Default behavior: emit 504 unconditionally for lambda/http/aws-service
-     * integrations because the timeout *can* fire.
+     * The integration timeout from the manifest. Summaries do not read it
+     * yet: a 504 is added for every integration that can time out, since
+     * the platform cap (29s for REST, 30s for HTTP APIs) always applies.
      */
     timeoutMs?: number;
     configRef?: ConfigRef;
@@ -109,38 +108,35 @@ interface RestEndpointConfig {
     path: string;
     integration: IntegrationConfig;
     /**
-     * `null` (or undefined) means no authorizer. To opt out of an
-     * inherited API-level default, pass `null` explicitly.
+     * Undefined inherits the API's default authorizer, and `null` turns it
+     * off for this endpoint.
      */
     authorizer?: AuthorizerConfig | null;
     apiKeyRequired?: boolean;
     requestValidation?: RequestValidationConfig;
     throttle?: ThrottleConfig;
-    /**
-     * Optional override label for the synthesized handler name. Defaults
-     * to `${method.toUpperCase()} ${path}`.
-     */
+    /** The summary's name. Defaults to `<api id>:<METHOD>:<path>`. */
     name?: string;
     /**
-     * Code that implements this endpoint, when the manifest says which
-     * (SAM Lambda proxy `Handler`). Emitted as
-     * `metadata.http.implementingHandler`; purely additive.
+     * The code behind this endpoint, when the manifest says which, as a SAM
+     * Lambda proxy `Handler` does. Copied to
+     * `metadata.http.implementingHandler`.
      */
     implementingHandler?: HandlerPointer;
     configRef?: ConfigRef;
 }
 interface RestApiConfig {
-    /** Logical identifier for the API (used in summary identity). */
+    /** The API's logical id, used in each summary's name. */
     id: string;
     /** Recorded as `SourceLocation.file` on each summary. */
     source?: string;
     endpoints: RestEndpointConfig[];
-    /** API-level defaults that cascade onto endpoints unless overridden. */
+    /** Applies to every endpoint that does not set its own. */
     defaultAuthorizer?: AuthorizerConfig;
     defaultThrottle?: ThrottleConfig;
-    /** API-level CORS: produces an OPTIONS endpoint per resource path. */
+    /** Adds an OPTIONS preflight summary for each resource path. */
     cors?: CorsConfig;
-    /** Binary media types declared on the API; doesn't affect transitions. */
+    /** Recorded from the manifest. No transition depends on it. */
     binaryMediaTypes?: string[];
 }
 type HttpAuthorizerType = "jwt" | "lambda-request" | "iam";
@@ -151,9 +147,9 @@ interface HttpAuthorizerConfig {
 }
 interface HttpRouteConfig {
     /**
-     * Route key in API Gateway's native form: `"<METHOD> <path>"`, or
-     * `"$default"` for the catch-all route. The package re-parses this
-     * to fill `BoundaryBinding.method` / `path`.
+     * API Gateway's route key, `"<METHOD> <path>"`, or `"$default"` for the
+     * catch-all route. The method and path in the binding are parsed from
+     * it, and a `$default` route gets no summary.
      */
     routeKey: string;
     integration: IntegrationConfig;
@@ -161,9 +157,9 @@ interface HttpRouteConfig {
     throttle?: ThrottleConfig;
     name?: string;
     /**
-     * Code that implements this route, when the manifest says which (SAM
-     * Lambda proxy `Handler`). Emitted as
-     * `metadata.http.implementingHandler`; purely additive.
+     * The code behind this route, when the manifest says which, as a SAM
+     * Lambda proxy `Handler` does. Copied to
+     * `metadata.http.implementingHandler`.
      */
     implementingHandler?: HandlerPointer;
     configRef?: ConfigRef;
@@ -177,8 +173,19 @@ interface HttpApiConfig {
     cors?: CorsConfig;
 }
 
+/**
+ * Turns an HttpApiConfig (API Gateway v2) into one summary per route. The
+ * platform adds the same status codes as for a REST API, except that an
+ * HTTP API has no API keys and no request validation.
+ */
+
 declare function httpApiToSummaries(config: HttpApiConfig): BehavioralSummary[];
 
+/**
+ * Turns a RestApiConfig into one summary per endpoint, adding the
+ * responses API Gateway v1 (REST) returns for each configuration setting.
+ */
+
 declare function restApiToSummaries(config: RestApiConfig): BehavioralSummary[];
 
 export { type AuthorizerConfig, type AuthorizerType, type ConfigRef, type CorsConfig, type HandlerPointer, type HttpApiConfig, type HttpAuthorizerConfig, type HttpAuthorizerType, type HttpRouteConfig, type IntegrationConfig, type IntegrationType, type PlatformCause, type RequestValidationConfig, type RestApiConfig, type RestEndpointConfig, type ThrottleConfig, httpApiToSummaries, restApiToSummaries };

package/dist/index.d.ts

@@ -1,11 +1,18 @@
 import { BehavioralSummary } from '@suss/behavioral-ir';
 
 /**
- * Reference back into the source manifest that introduced a piece of
- * configuration. Carried in `Transition.metadata.configRef` so inspect/
- * diff can attribute platform-injected transitions to the file + path
- * where the user authored them. Always emit an absolute file path; the
- * pointer is a JSON-Pointer-ish hint, intentionally not validated.
+ * The configuration a manifest reader builds and passes to
+ * restApiToSummaries or httpApiToSummaries, whatever format it read.
+ *
+ * Besides routes, it includes the settings that change behavior:
+ * authorizers, CORS, throttling and request validation. Each one adds
+ * responses the platform returns that no handler code shows.
+ */
+/**
+ * Where in the source manifest a piece of configuration was written.
+ * Inspect and diff use it to point a platform-added response at the line
+ * that caused it. The file is always absolute, and the pointer is a hint
+ * in the style of a JSON Pointer that nothing validates.
  */
 interface ConfigRef {
     /** Absolute path to the source manifest file. */
@@ -14,20 +21,18 @@ interface ConfigRef {
     pointer: string;
 }
 /**
- * One of the well-known platform contracts that produce extra response
- * transitions. Used as the `cause` token in opaque predicates and as a
- * key for collapsing per-status transitions. Closed enum so the checker
- * and renderers can switch on it.
+ * The platform behaviors that add responses. Each value is the `cause` in
+ * a platform transition's metadata, and every cause that lands on one
+ * status code is merged into a single transition.
  */
 type PlatformCause = "authorization" | "api-key" | "request-validation" | "throttle" | "integration-timeout" | "integration-failure" | "cors-preflight";
 type AuthorizerType = "iam" | "cognito" | "lambda-token" | "lambda-request" | "jwt";
 interface AuthorizerConfig {
     type: AuthorizerType;
     /**
-     * When true, missing/invalid credentials produce 401; authenticated
-     * but denied produces 403. When false, the authorizer is configured
-     * but anonymous calls bypass it (mostly relevant for public-fallback
-     * IAM and Lambda authorizers with caching off).
+     * When true or unset, missing or invalid credentials return 401 and a
+     * denied caller gets 403. When false, anonymous calls pass the
+     * authorizer, so only 403 is added.
      */
     identitySourceRequired?: boolean;
     configRef?: ConfigRef;
@@ -53,22 +58,20 @@ interface RequestValidationConfig {
     configRef?: ConfigRef;
 }
 /**
- * Pointer from a declared route to the code that implements it. A
- * manifest reader (CFN/SAM, CDK, Terraform) fills this in when it knows
- * which module + export backs the route, e.g. a SAM Lambda proxy
- * integration whose `Handler` gives the file and export. The fields are
- * generic "where is the code" identity, not any one manifest's
- * semantics; `aws-apigateway` puts the pointer onto the summary
- * (`metadata.http.implementingHandler`) without interpreting it, so a
- * checker can later correlate the declared route with the extracted
- * handler summary with the same REST binding.
+ * The code that implements a declared route. A manifest reader fills it
+ * in when it can tell which module and export serve the route, as with a
+ * SAM Lambda proxy integration whose `Handler` gives both.
+ *
+ * This package copies it to `metadata.http.implementingHandler` without
+ * reading it, so the checker can match the declared route to the handler
+ * summary extracted from that code.
  */
 interface HandlerPointer {
     /** Raw handler reference, e.g. "src/handlers/confirmToken.handler". */
     handler: string;
     /** Module-path portion (before the final dot), e.g. "src/handlers/confirmToken". */
     modulePath: string;
-    /** Exported symbol the handler names, e.g. "handler". */
+    /** The exported function, e.g. "handler". */
     exportName: string;
     /** Base directory the module path resolves against (SAM CodeUri). */
     codeUri?: string;
@@ -77,28 +80,24 @@ interface HandlerPointer {
 }
 type IntegrationType = "lambda" | "lambda-proxy" | "http" | "http-proxy" | "mock" | "aws-service" | "vpc-link"
 /**
- * The manifest declared an endpoint but didn't specify the integration
- * type. We can't claim 502/504 will fire without knowing what's behind
- * the route, so platform-failure transitions are suppressed for this
- * type. Used by manifest readers as a fallback rather than fabricating
- * a guessed integration.
+ * The manifest declared an endpoint without an integration type. A
+ * reader uses this in place of a guess, and no 502 or 504 is added,
+ * because nothing is known about the backend.
  */
  | "unknown";
 interface IntegrationConfig {
     type: IntegrationType;
     /**
-     * Status codes the backend integration can produce. For proxy
-     * integrations this is what the handler emits; for non-proxy it's
-     * what `IntegrationResponses` map to. Empty array is allowed and
-     * means "we don't know", only platform-injected transitions will
-     * be emitted.
+     * Status codes the backend can return: what the handler returns for a
+     * proxy integration, or what `IntegrationResponses` map to otherwise.
+     * An empty array means they are unknown, and only the platform's
+     * responses are emitted.
      */
     statusCodes: number[];
     /**
-     * REST API Gateway hard cap is 29s; HTTP API is 30s. When set,
-     * a synthetic 504 is added if the integration could exceed it.
-     * Default behavior: emit 504 unconditionally for lambda/http/aws-service
-     * integrations because the timeout *can* fire.
+     * The integration timeout from the manifest. Summaries do not read it
+     * yet: a 504 is added for every integration that can time out, since
+     * the platform cap (29s for REST, 30s for HTTP APIs) always applies.
      */
     timeoutMs?: number;
     configRef?: ConfigRef;
@@ -109,38 +108,35 @@ interface RestEndpointConfig {
     path: string;
     integration: IntegrationConfig;
     /**
-     * `null` (or undefined) means no authorizer. To opt out of an
-     * inherited API-level default, pass `null` explicitly.
+     * Undefined inherits the API's default authorizer, and `null` turns it
+     * off for this endpoint.
      */
     authorizer?: AuthorizerConfig | null;
     apiKeyRequired?: boolean;
     requestValidation?: RequestValidationConfig;
     throttle?: ThrottleConfig;
-    /**
-     * Optional override label for the synthesized handler name. Defaults
-     * to `${method.toUpperCase()} ${path}`.
-     */
+    /** The summary's name. Defaults to `<api id>:<METHOD>:<path>`. */
     name?: string;
     /**
-     * Code that implements this endpoint, when the manifest says which
-     * (SAM Lambda proxy `Handler`). Emitted as
-     * `metadata.http.implementingHandler`; purely additive.
+     * The code behind this endpoint, when the manifest says which, as a SAM
+     * Lambda proxy `Handler` does. Copied to
+     * `metadata.http.implementingHandler`.
      */
     implementingHandler?: HandlerPointer;
     configRef?: ConfigRef;
 }
 interface RestApiConfig {
-    /** Logical identifier for the API (used in summary identity). */
+    /** The API's logical id, used in each summary's name. */
     id: string;
     /** Recorded as `SourceLocation.file` on each summary. */
     source?: string;
     endpoints: RestEndpointConfig[];
-    /** API-level defaults that cascade onto endpoints unless overridden. */
+    /** Applies to every endpoint that does not set its own. */
     defaultAuthorizer?: AuthorizerConfig;
     defaultThrottle?: ThrottleConfig;
-    /** API-level CORS: produces an OPTIONS endpoint per resource path. */
+    /** Adds an OPTIONS preflight summary for each resource path. */
     cors?: CorsConfig;
-    /** Binary media types declared on the API; doesn't affect transitions. */
+    /** Recorded from the manifest. No transition depends on it. */
     binaryMediaTypes?: string[];
 }
 type HttpAuthorizerType = "jwt" | "lambda-request" | "iam";
@@ -151,9 +147,9 @@ interface HttpAuthorizerConfig {
 }
 interface HttpRouteConfig {
     /**
-     * Route key in API Gateway's native form: `"<METHOD> <path>"`, or
-     * `"$default"` for the catch-all route. The package re-parses this
-     * to fill `BoundaryBinding.method` / `path`.
+     * API Gateway's route key, `"<METHOD> <path>"`, or `"$default"` for the
+     * catch-all route. The method and path in the binding are parsed from
+     * it, and a `$default` route gets no summary.
      */
     routeKey: string;
     integration: IntegrationConfig;
@@ -161,9 +157,9 @@ interface HttpRouteConfig {
     throttle?: ThrottleConfig;
     name?: string;
     /**
-     * Code that implements this route, when the manifest says which (SAM
-     * Lambda proxy `Handler`). Emitted as
-     * `metadata.http.implementingHandler`; purely additive.
+     * The code behind this route, when the manifest says which, as a SAM
+     * Lambda proxy `Handler` does. Copied to
+     * `metadata.http.implementingHandler`.
      */
     implementingHandler?: HandlerPointer;
     configRef?: ConfigRef;
@@ -177,8 +173,19 @@ interface HttpApiConfig {
     cors?: CorsConfig;
 }
 
+/**
+ * Turns an HttpApiConfig (API Gateway v2) into one summary per route. The
+ * platform adds the same status codes as for a REST API, except that an
+ * HTTP API has no API keys and no request validation.
+ */
+
 declare function httpApiToSummaries(config: HttpApiConfig): BehavioralSummary[];
 
+/**
+ * Turns a RestApiConfig into one summary per endpoint, adding the
+ * responses API Gateway v1 (REST) returns for each configuration setting.
+ */
+
 declare function restApiToSummaries(config: RestApiConfig): BehavioralSummary[];
 
 export { type AuthorizerConfig, type AuthorizerType, type ConfigRef, type CorsConfig, type HandlerPointer, type HttpApiConfig, type HttpAuthorizerConfig, type HttpAuthorizerType, type HttpRouteConfig, type IntegrationConfig, type IntegrationType, type PlatformCause, type RequestValidationConfig, type RestApiConfig, type RestEndpointConfig, type ThrottleConfig, httpApiToSummaries, restApiToSummaries };

package/dist/index.js

@@ -290,10 +290,6 @@ function buildRouteSummary(route, parsed, api, sourceFile) {
             statusCode
           }))
         },
-        // Additive pointer to the code that implements this route (SAM
-        // Lambda proxy Handler), so a checker can correlate the declared
-        // route with the extracted handler summary carrying the same
-        // REST binding.
         ...route.implementingHandler !== void 0 ? { implementingHandler: route.implementingHandler } : {}
       }
     )
@@ -456,13 +452,9 @@ function buildEndpointSummary(endpoint, api, sourceFile) {
         integrationType: endpoint.integration.type
       },
       {
-        // The integration's declared status codes (from MethodResponses
-        // in the CFN template) are the declared contract here.
-        // Platform-injected transitions (authorizer 401/403, throttle
-        // 429, etc.) come from SEPARATE config fields and so are
-        // independent from this contract: contract-consistency
-        // comparison is meaningful and will surface template-internal
-        // inconsistencies.
+        // The platform's responses come from other settings than
+        // MethodResponses, so comparing them with this contract can find
+        // a template that contradicts itself.
         declaredContract: {
           framework: FRAMEWORK,
           provenance: "independent",
@@ -470,10 +462,6 @@ function buildEndpointSummary(endpoint, api, sourceFile) {
             statusCode
           }))
         },
-        // Additive pointer to the code that implements this endpoint
-        // (SAM Lambda proxy Handler), so a checker can correlate the
-        // declared route with the extracted handler summary carrying the
-        // same REST binding.
         ...endpoint.implementingHandler !== void 0 ? { implementingHandler: endpoint.implementingHandler } : {}
       }
     )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/contract-aws-apigateway",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "type": "module",
   "description": "Turn an AWS API Gateway REST or HTTP API into a suss contract and check it against the Lambda handlers and clients that use it.",
   "keywords": [
@@ -14,7 +14,7 @@
   ],
   "license": "Apache-2.0",
   "author": "Nimbus Cloud AI LLC",
-  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/contract/aws-apigateway#readme",
+  "homepage": "https://suss.sh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nimbuscloud-ai/suss.git",
@@ -47,7 +47,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.33.0"
+    "@suss/behavioral-ir": "0.34.0"
   },
   "devDependencies": {
     "tsup": "*",