cdktn 0.25.0-pre.39 → 0.25.0-pre.40

package/.jsii

@@ -1546,7 +1546,7 @@
     "cdktn.AssetHashType": {
       "assembly": "cdktn",
       "docs": {
-        "remarks": "NOTE: the hash is used in order to identify a specific revision of the asset, and\nused for optimizing and caching deployment activities related to this asset such as\npackaging, uploading to cloud storage, etc.",
+        "remarks": "The hash identifies a specific revision of the asset and caches deployment\nwork such as packaging and uploading.",
         "stability": "experimental",
         "summary": "The type of asset hash."
       },
@@ -1554,12 +1554,12 @@
       "kind": "enum",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 59
+        "line": 63
       },
       "members": [
         {
           "docs": {
-            "remarks": "Use `SOURCE` when the content of the asset changes frequently or when\nyou want to track changes to the source files directly.",
+            "remarks": "Use `SOURCE` to track changes to the source files directly.",
             "stability": "experimental",
             "summary": "Based on the content of the source path."
           },
@@ -1567,7 +1567,7 @@
         },
         {
           "docs": {
-            "remarks": "Use `OUTPUT` when the source of the asset is a top level folder containing\ncode and/or dependencies that are not directly linked to the asset.",
+            "remarks": "Use `OUTPUT` when the source is a top-level folder holding code and/or\ndependencies not directly linked to the asset.",
             "stability": "experimental",
             "summary": "Based on the content of the bundling output."
           },
@@ -1589,13 +1589,13 @@
       "datatype": true,
       "docs": {
         "stability": "experimental",
-        "summary": "Asset hash options."
+        "summary": "Options controlling how an asset's hash is derived."
       },
       "fqn": "cdktn.AssetOptions",
       "kind": "interface",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 23
+        "line": 30
       },
       "name": "AssetOptions",
       "properties": [
@@ -1603,14 +1603,14 @@
           "abstract": true,
           "docs": {
             "default": "- based on `assetHashType`",
-            "remarks": "If `assetHashType` is set it must\nbe set to `AssetHashType.CUSTOM`. The value is used verbatim as the asset\nhash, and because it names the staged asset file it may only contain\nletters, digits, `_`, `.` and `-`.\n\nNOTE: the hash is used in order to identify a specific revision of the asset, and\nused for optimizing and caching deployment activities related to this asset such as\npackaging, uploading to cloud storage, etc. If you chose to customize the hash, you will\nneed to make sure it is updated every time the asset changes, or otherwise it is\npossible that some deployments will not be invalidated.",
+            "remarks": "If `assetHashType` is set it must\nbe set to `AssetHashType.CUSTOM`. The value is used verbatim as the asset\nhash, and because it names the staged asset file it may only contain\nletters, digits, `_`, `.` and `-`.\n\nThe hash identifies a specific revision of the asset and caches deployment\nwork (packaging, uploading). A custom hash must be updated whenever the\nasset changes, or some deployments will not be invalidated.",
             "stability": "experimental",
             "summary": "Specify a custom hash for this asset."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 38
+            "line": 43
           },
           "name": "assetHash",
           "optional": true,
@@ -1629,7 +1629,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 49
+            "line": 54
           },
           "name": "assetHashType",
           "optional": true,
@@ -1651,7 +1651,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 220
+        "line": 223
       },
       "name": "AssetPackaging",
       "properties": [
@@ -1664,7 +1664,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 229
+            "line": 232
           },
           "name": "DIRECTORY",
           "static": true,
@@ -1681,7 +1681,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 224
+            "line": 227
           },
           "name": "FILE",
           "static": true,
@@ -1698,7 +1698,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 234
+            "line": 237
           },
           "name": "ZIP",
           "static": true,
@@ -1724,7 +1724,7 @@
         },
         "locationInModule": {
           "filename": "src/asset-staging.ts",
-          "line": 220
+          "line": 231
         },
         "parameters": [
           {
@@ -1753,7 +1753,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/asset-staging.ts",
-        "line": 193
+        "line": 200
       },
       "methods": [
         {
@@ -1764,7 +1764,7 @@
           },
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 420
+            "line": 499
           },
           "name": "stage",
           "parameters": [
@@ -1781,14 +1781,14 @@
       "properties": [
         {
           "docs": {
-            "remarks": "As this is a plain string, it\ncan be used in construct IDs in order to enforce creation of a new resource when the content\nhash has changed.",
+            "remarks": "Being a plain string, it can be used in construct IDs to force a new\nresource when the content hash changes.",
             "stability": "experimental",
-            "summary": "A hash of this asset, which is available at construction time."
+            "summary": "A hash of this asset, available at construction time."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 218
+            "line": 229
           },
           "name": "assetHash",
           "overrides": "cdktn.IAsset",
@@ -1803,7 +1803,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 217
+            "line": 228
           },
           "name": "isDirectory",
           "type": {
@@ -1817,7 +1817,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 216
+            "line": 227
           },
           "name": "packaging",
           "type": {
@@ -1841,7 +1841,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/asset-staging.ts",
-        "line": 123
+        "line": 128
       },
       "name": "AssetStagingOptions",
       "properties": [
@@ -1855,7 +1855,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 135
+            "line": 140
           },
           "name": "packaging",
           "type": {
@@ -1872,7 +1872,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 128
+            "line": 133
           },
           "name": "sourcePath",
           "type": {
@@ -1883,14 +1883,14 @@
           "abstract": true,
           "docs": {
             "default": "- the source is staged verbatim, with no build step",
-            "remarks": "Under the default `SOURCE` hashing the build is deferred to `stage()` and\nstays skippable; `OUTPUT` hashing builds eagerly at construction time to\nhash the artifact, forgoing skippability. A bundler always produces a\ndirectory, so single-file packaging (`AssetType.FILE`) is rejected.",
+            "remarks": "Under the default `SOURCE` hashing the build is deferred to `stage()` and\nstays skippable; `OUTPUT` hashing builds eagerly at construction time to\nhash the artifact, forgoing skippability. The bundler's declared output\nshape must match the packaging: a `BundleResult.directory` needs a\ndirectory-accepting packaging, a `BundleResult.file` a single-file one\n(`AssetType.FILE`). The mismatch is caught once the build runs.",
             "stability": "experimental",
             "summary": "A bundler that builds the source into an artifact before staging."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 172
+            "line": 179
           },
           "name": "bundler",
           "optional": true,
@@ -1908,7 +1908,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 180
+            "line": 187
           },
           "name": "displayName",
           "optional": true,
@@ -1927,7 +1927,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 144
+            "line": 149
           },
           "name": "exclude",
           "optional": true,
@@ -1950,7 +1950,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 160
+            "line": 165
           },
           "name": "extraHash",
           "optional": true,
@@ -1968,7 +1968,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 152
+            "line": 157
           },
           "name": "ignoreStrategy",
           "optional": true,
@@ -1988,7 +1988,7 @@
       "kind": "enum",
       "locationInModule": {
         "filename": "src/terraform-asset.ts",
-        "line": 76
+        "line": 78
       },
       "members": [
         {
@@ -3432,21 +3432,21 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 246
+        "line": 249
       },
       "name": "BundleOptions",
       "properties": [
         {
           "abstract": true,
           "docs": {
-            "remarks": "The bundler produces its output here (or in a subdirectory) and\nreturns the directory that holds the finished artifact — see\n{@link IAssetBundler.bundle}.",
+            "remarks": "The bundler produces its output here (or in a subdirectory) and\nreturns a {@link BundleResult} pointing at the finished artifact — see\n{@link IAssetBundler.bundle}.",
             "stability": "experimental",
             "summary": "A scratch directory the bundler may write into, owned and created by the caller."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 263
+            "line": 266
           },
           "name": "outputDir",
           "type": {
@@ -3463,7 +3463,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 255
+            "line": 258
           },
           "name": "source",
           "type": {
@@ -3473,11 +3473,179 @@
       ],
       "symbolId": "src/assets:BundleOptions"
     },
+    "cdktn.BundleOutputType": {
+      "assembly": "cdktn",
+      "docs": {
+        "stability": "experimental",
+        "summary": "The shape of a bundler's output, so staging and packaging can treat a single-file artifact (a tarball, a `.zip`) differently from a directory tree without inferring it from the path."
+      },
+      "fqn": "cdktn.BundleOutputType",
+      "kind": "enum",
+      "locationInModule": {
+        "filename": "src/assets.ts",
+        "line": 274
+      },
+      "members": [
+        {
+          "docs": {
+            "remarks": "Packaged like an unbundled source directory. The default, and the only\nshape that predates archive support.",
+            "stability": "experimental",
+            "summary": "The output is a directory tree."
+          },
+          "name": "DIRECTORY"
+        },
+        {
+          "docs": {
+            "remarks": "A tarball or a deterministic `.zip`. Staged verbatim rather than\nre-archived, so `AssetType.FILE` no longer has to reject a bundler.",
+            "stability": "experimental",
+            "summary": "The output is a single file the bundler already produced in its final form."
+          },
+          "name": "FILE"
+        }
+      ],
+      "name": "BundleOutputType",
+      "symbolId": "src/assets:BundleOutputType"
+    },
+    "cdktn.BundleResult": {
+      "assembly": "cdktn",
+      "docs": {
+        "remarks": "Carries the artifact path and its shape, or a declined state signalling the\ncaller should fall back. See {@link declined} for the decline protocol.",
+        "stability": "experimental",
+        "summary": "What a bundler produced, returned from {@link IAssetBundler.bundle}."
+      },
+      "fqn": "cdktn.BundleResult",
+      "kind": "class",
+      "locationInModule": {
+        "filename": "src/assets.ts",
+        "line": 299
+      },
+      "methods": [
+        {
+          "docs": {
+            "remarks": "Distinct from a thrown error, which is a hard failure.",
+            "stability": "experimental",
+            "summary": "The bundler declined to run here; the caller should fall back."
+          },
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 319
+          },
+          "name": "declined",
+          "returns": {
+            "type": {
+              "fqn": "cdktn.BundleResult"
+            }
+          },
+          "static": true
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "A directory-tree artifact at `path`."
+          },
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 303
+          },
+          "name": "directory",
+          "parameters": [
+            {
+              "name": "path",
+              "type": {
+                "primitive": "string"
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "fqn": "cdktn.BundleResult"
+            }
+          },
+          "static": true
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "A single-file artifact at `path` (a tarball, a `.zip`), staged verbatim."
+          },
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 310
+          },
+          "name": "file",
+          "parameters": [
+            {
+              "name": "path",
+              "type": {
+                "primitive": "string"
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "fqn": "cdktn.BundleResult"
+            }
+          },
+          "static": true
+        }
+      ],
+      "name": "BundleResult",
+      "properties": [
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "Whether the bundler declined to run, signalling the caller to fall back."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 336
+          },
+          "name": "isDeclined",
+          "type": {
+            "primitive": "boolean"
+          }
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "The artifact's shape, or undefined when {@link isDeclined}."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 326
+          },
+          "name": "outputType",
+          "optional": true,
+          "type": {
+            "fqn": "cdktn.BundleOutputType"
+          }
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "The artifact path, or undefined when {@link isDeclined}."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 331
+          },
+          "name": "path",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "symbolId": "src/assets:BundleResult"
+    },
     "cdktn.BundlerKey": {
       "assembly": "cdktn",
       "docs": {
         "example": "const key = BundlerKey.of(\"docker\", image, command)\n  .withEnv({ NODE_ENV: nodeEnv })\n  .toString();",
-        "remarks": "A `bundlerKey` has to serialize everything that can move a build's output;\ndone ad hoc, every bundler invents its own delimiter and forgets an input\ndifferently. This gives the convention one implementation: parts are joined\nwith a separator that is escaped where it appears in a value, so distinct\ninputs can never collide into the same key (`[\"a:b\", \"c\"]` and\n`[\"a\", \"b:c\"]` stay different).",
+        "remarks": "A `bundlerKey` has to serialize everything that can move a build's output;\ndone ad hoc, every bundler invents its own delimiter and forgets an input\ndifferently. This gives the convention one implementation: parts are joined\nwith a separator that is escaped inside values, so distinct inputs cannot\ncollide into the same key.",
         "stability": "experimental",
         "summary": "Builds an {@link IAssetBundler.bundlerKey} from an ordered set of parts."
       },
@@ -3485,7 +3653,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 333
+        "line": 432
       },
       "methods": [
         {
@@ -3496,7 +3664,7 @@
           },
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 339
+            "line": 438
           },
           "name": "of",
           "parameters": [
@@ -3523,7 +3691,7 @@
           },
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 352
+            "line": 451
           },
           "name": "add",
           "parameters": [
@@ -3549,7 +3717,7 @@
           },
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 370
+            "line": 469
           },
           "name": "toString",
           "returns": {
@@ -3565,7 +3733,7 @@
           },
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 360
+            "line": 459
           },
           "name": "withEnv",
           "parameters": [
@@ -3591,6 +3759,119 @@
       "name": "BundlerKey",
       "symbolId": "src/assets:BundlerKey"
     },
+    "cdktn.ChainBundler": {
+      "assembly": "cdktn",
+      "docs": {
+        "remarks": "This is how a local bundler and a Docker bundler compose without being\nrewritten as one: each leg declines (`BundleResult.declined()`) when it\ncannot run here, and the chain moves to the next. The first non-declining\nresult wins; if all decline, `bundle` throws, since staging has nothing to\nfall back to. Each leg builds into its own output directory, so a leg that\nwrites before declining cannot leak partial files into the leg that wins.\n\nThe chain's `bundlerKey` folds in *every* leg's key, so identity is the same\nregardless of which leg ends up running — a build that could have gone local\nor Docker is one asset, not two.\n\nThis makes the legs interchangeable only if they produce equivalent output.\nUnder `SOURCE` hashing they must: a machine with a host tool and one without\nrun different legs, and non-equivalent legs would stage different bytes under\nthe same hash. Use `OUTPUT` hashing when legs may diverge, so identity tracks\nthe artifact each leg actually produced.",
+        "stability": "experimental",
+        "summary": "Composes bundlers into a \"try each in order until one runs\" chain."
+      },
+      "fqn": "cdktn.ChainBundler",
+      "interfaces": [
+        "cdktn.IAssetBundler"
+      ],
+      "kind": "class",
+      "locationInModule": {
+        "filename": "src/assets.ts",
+        "line": 494
+      },
+      "methods": [
+        {
+          "docs": {
+            "remarks": "earlier bundlers are preferred.",
+            "stability": "experimental",
+            "summary": "Chain bundlers in the order given;"
+          },
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 498
+          },
+          "name": "of",
+          "parameters": [
+            {
+              "name": "bundlers",
+              "type": {
+                "fqn": "cdktn.IAssetBundler"
+              },
+              "variadic": true
+            }
+          ],
+          "returns": {
+            "type": {
+              "fqn": "cdktn.ChainBundler"
+            }
+          },
+          "static": true,
+          "variadic": true
+        },
+        {
+          "docs": {
+            "remarks": "Implementations write into `options.outputDir` and never write back to\n`options.source`. The returned path must exist and match its declared\nshape, or staging rejects it.\n\nA bundler that cannot run in this environment returns\n`BundleResult.declined()` so a {@link ChainBundler} can fall through to\nthe next; a thrown error is a hard failure, not a decline.",
+            "stability": "experimental",
+            "summary": "Produce the artifact and return a {@link BundleResult} describing it."
+          },
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 532
+          },
+          "name": "bundle",
+          "overrides": "cdktn.IAssetBundler",
+          "parameters": [
+            {
+              "name": "options",
+              "type": {
+                "fqn": "cdktn.BundleOptions"
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "fqn": "cdktn.BundleResult"
+            }
+          }
+        }
+      ],
+      "name": "ChainBundler",
+      "properties": [
+        {
+          "docs": {
+            "remarks": "The source tree alone cannot see the build, so swapping a `node:18` base\nimage for `node:20` would otherwise leave identity unchanged. Under\n`SOURCE` hashing this is the only channel by which the build reaches\nidentity, so it must serialize every input that can move the output, or a\nchanged build silently reuses a stale artifact. {@link BundlerKey} builds\none from an ordered set of parts.\n\nMirrors {@link IIgnoreStrategy.cacheKey}: omit it when the build cannot be\nsummarized as a string, and fall back to `extraHash`.",
+            "stability": "experimental",
+            "summary": "A value identifying the build, folded into the asset hash."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 502
+          },
+          "name": "bundlerKey",
+          "optional": true,
+          "overrides": "cdktn.IAssetBundler",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "docs": {
+            "remarks": "A file-producing bundler (`BundleResult.file`) staged with\n`AssetType.FILE` would otherwise take the source path's basename, which is\na directory name when the source is a directory. Declaring the name here\nlets the artifact reflect what the bundler produces. It is static\nconfiguration, needed at construction before a deferred `SOURCE` build\nruns, not the file's runtime name.\n\nValid only for a file-producing bundler: setting it with a directory\npackaging (anything but `AssetType.FILE`) is rejected at construction.",
+            "stability": "experimental",
+            "summary": "The name a single-file artifact is staged under (e.g. `archive.zip`)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 504
+          },
+          "name": "outputFileName",
+          "optional": true,
+          "overrides": "cdktn.IAssetBundler",
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "symbolId": "src/assets:ChainBundler"
+    },
     "cdktn.CloudBackend": {
       "assembly": "cdktn",
       "base": "cdktn.TerraformBackend",
@@ -12261,21 +12542,21 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 11
+        "line": 17
       },
       "name": "IAsset",
       "properties": [
         {
           "abstract": true,
           "docs": {
-            "remarks": "As this is a plain string, it\ncan be used in construct IDs in order to enforce creation of a new resource when the content\nhash has changed.",
+            "remarks": "Being a plain string, it can be used in construct IDs to force a new\nresource when the content hash changes.",
             "stability": "experimental",
-            "summary": "A hash of this asset, which is available at construction time."
+            "summary": "A hash of this asset, available at construction time."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 17
+            "line": 24
           },
           "name": "assetHash",
           "type": {
@@ -12288,7 +12569,7 @@
     "cdktn.IAssetBundler": {
       "assembly": "cdktn",
       "docs": {
-        "remarks": "This is the extension point for asset bundling: core ships no bundler.\nDocker, esbuild, pip, `go build`, and similar are an open-ended set that\nis not cloud-specific, so each lives in its own package and implements this\none interface — the same way {@link IIgnoreStrategy} lets richer exclusion\nlive outside core without core taking on a glob parser. A third party\ndevelops a bundler by implementing this interface and publishing it as a\npackage; users pass an instance via the consuming construct's `bundler`\noption.\n\n`bundle` runs during the owning construct's `onSynthesize` hook and may\ntouch the filesystem. Deferring it there keeps it skippable when the asset's\nstack is not being synthesized, which holds as long as the hash is taken\nover the source rather than the built output.",
+        "remarks": "This is the extension point for asset bundling: core ships no bundler.\nDocker, esbuild, pip, `go build`, and similar are an open-ended, non\ncloud-specific set, so each lives in its own package and implements this\none interface — the same way {@link IIgnoreStrategy} lets richer exclusion\nlive outside core. Users pass an instance via the consuming construct's\n`bundler` option.\n\n`bundle` runs during the owning construct's `onSynthesize` hook and may\ntouch the filesystem. Deferring it there keeps it skippable when the asset's\nstack is not being synthesized, which holds as long as the hash is taken\nover the source rather than the built output.\n\nBundlers compose through {@link ChainBundler} rather than a hierarchy: a\nbundler declines (see {@link BundleResult.declined}) instead of failing when\nit cannot run, and the chain falls through to the next.",
         "stability": "experimental",
         "summary": "Transforms a source tree into a built artifact. Runs at synth, before the output is packaged and staged."
       },
@@ -12296,19 +12577,19 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 284
+        "line": 369
       },
       "methods": [
         {
           "abstract": true,
           "docs": {
-            "remarks": "Implementations write into `options.outputDir` and return it or a\nsubdirectory, never writing back to `options.source`. The returned\ndirectory is then packaged as an unbundled source directory would be.\nReturning a file, or a path that does not exist, is rejected — the\ncontract is a directory, and packaging always treats the result as one.",
+            "remarks": "Implementations write into `options.outputDir` and never write back to\n`options.source`. The returned path must exist and match its declared\nshape, or staging rejects it.\n\nA bundler that cannot run in this environment returns\n`BundleResult.declined()` so a {@link ChainBundler} can fall through to\nthe next; a thrown error is a hard failure, not a decline.",
             "stability": "experimental",
-            "summary": "Produce the artifact and return the directory holding it."
+            "summary": "Produce the artifact and return a {@link BundleResult} describing it."
           },
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 315
+            "line": 415
           },
           "name": "bundle",
           "parameters": [
@@ -12321,7 +12602,7 @@
           ],
           "returns": {
             "type": {
-              "primitive": "string"
+              "fqn": "cdktn.BundleResult"
             }
           }
         }
@@ -12332,20 +12613,39 @@
           "abstract": true,
           "docs": {
             "default": "- the build does not contribute to the hash",
-            "remarks": "The source tree alone cannot see the build, so swapping a `node:18` base\nimage for `node:20` would otherwise leave identity unchanged. A value\ncapturing the build (e.g. `docker:<image>:<command>`) closes that gap.\n\nUnder `SOURCE` hashing this is the only channel by which the build reaches\nidentity, so it must serialize every input that can move the output —\nbase image, command, tool version, environment, arguments. Anything left\nout means a changed build silently reuses a stale artifact. {@link * BundlerKey} builds one from an ordered set of parts so the format is not\nreinvented per bundler.\n\nMirrors {@link IIgnoreStrategy.cacheKey}: omit it when the build cannot be\nsummarized as a string, and fall back to `extraHash`.",
+            "remarks": "The source tree alone cannot see the build, so swapping a `node:18` base\nimage for `node:20` would otherwise leave identity unchanged. Under\n`SOURCE` hashing this is the only channel by which the build reaches\nidentity, so it must serialize every input that can move the output, or a\nchanged build silently reuses a stale artifact. {@link BundlerKey} builds\none from an ordered set of parts.\n\nMirrors {@link IIgnoreStrategy.cacheKey}: omit it when the build cannot be\nsummarized as a string, and fall back to `extraHash`.",
             "stability": "experimental",
             "summary": "A value identifying the build, folded into the asset hash."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 304
+            "line": 385
           },
           "name": "bundlerKey",
           "optional": true,
           "type": {
             "primitive": "string"
           }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- the source path's basename",
+            "remarks": "A file-producing bundler (`BundleResult.file`) staged with\n`AssetType.FILE` would otherwise take the source path's basename, which is\na directory name when the source is a directory. Declaring the name here\nlets the artifact reflect what the bundler produces. It is static\nconfiguration, needed at construction before a deferred `SOURCE` build\nruns, not the file's runtime name.\n\nValid only for a file-producing bundler: setting it with a directory\npackaging (anything but `AssetType.FILE`) is rejected at construction.",
+            "stability": "experimental",
+            "summary": "The name a single-file artifact is staged under (e.g. `archive.zip`)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 402
+          },
+          "name": "outputFileName",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
         }
       ],
       "symbolId": "src/assets:IAssetBundler"
@@ -12361,7 +12661,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 91
+        "line": 94
       },
       "methods": [
         {
@@ -12372,7 +12672,7 @@
           },
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 131
+            "line": 134
           },
           "name": "pack",
           "parameters": [
@@ -12397,7 +12697,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 113
+            "line": 116
           },
           "name": "acceptsDirectorySource",
           "type": {
@@ -12413,7 +12713,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 95
+            "line": 98
           },
           "name": "extension",
           "type": {
@@ -12430,7 +12730,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 126
+            "line": 129
           },
           "name": "omitsDirectoryEntries",
           "type": {
@@ -12447,7 +12747,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 103
+            "line": 106
           },
           "name": "producesDirectory",
           "type": {
@@ -17577,7 +17877,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 141
+        "line": 144
       },
       "name": "PackOptions",
       "properties": [
@@ -17590,7 +17890,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 145
+            "line": 148
           },
           "name": "source",
           "type": {
@@ -17606,7 +17906,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 150
+            "line": 153
           },
           "name": "target",
           "type": {
@@ -17624,7 +17924,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 159
+            "line": 162
           },
           "name": "ignoreStrategy",
           "optional": true,
@@ -20743,21 +21043,21 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 383
+        "line": 560
       },
       "name": "StagedAsset",
       "properties": [
         {
           "abstract": true,
           "docs": {
-            "remarks": "This hash is used to uniquely identify this\nasset throughout the system. If this value doesn't change, the asset will\nnot be rebuilt or republished.",
+            "remarks": "The asset is not rebuilt or republished while this value is unchanged.",
             "stability": "experimental",
-            "summary": "A hash on the content source."
+            "summary": "A hash on the content source, uniquely identifying this asset."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 389
+            "line": 566
           },
           "name": "assetHash",
           "type": {
@@ -20774,7 +21074,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 402
+            "line": 579
           },
           "name": "isDirectory",
           "type": {
@@ -20790,7 +21090,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 394
+            "line": 571
           },
           "name": "path",
           "type": {
@@ -22275,7 +22575,7 @@
         },
         "locationInModule": {
           "filename": "src/terraform-asset.ts",
-          "line": 117
+          "line": 125
         },
         "parameters": [
           {
@@ -22304,20 +22604,20 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/terraform-asset.ts",
-        "line": 100
+        "line": 108
       },
       "name": "TerraformAsset",
       "properties": [
         {
           "docs": {
-            "remarks": "As this is a plain string, it\ncan be used in construct IDs in order to enforce creation of a new resource when the content\nhash has changed.",
+            "remarks": "Being a plain string, it can be used in construct IDs to force a new\nresource when the content hash changes.",
             "stability": "experimental",
-            "summary": "A hash of this asset, which is available at construction time."
+            "summary": "A hash of this asset, available at construction time."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 104
+            "line": 112
           },
           "name": "assetHash",
           "overrides": "cdktn.IAsset",
@@ -22333,7 +22633,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 205
+            "line": 230
           },
           "name": "fileName",
           "type": {
@@ -22348,7 +22648,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 192
+            "line": 217
           },
           "name": "path",
           "type": {
@@ -22361,7 +22661,7 @@
           },
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 106
+            "line": 114
           },
           "name": "type",
           "type": {
@@ -22381,7 +22681,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/terraform-asset.ts",
-        "line": 24
+        "line": 26
       },
       "name": "TerraformAssetConfig",
       "properties": [
@@ -22393,7 +22693,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 26
+            "line": 28
           },
           "name": "path",
           "type": {
@@ -22408,7 +22708,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 30
+            "line": 32
           },
           "name": "assetHash",
           "optional": true,
@@ -22427,7 +22727,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 43
+            "line": 45
           },
           "name": "assetHashType",
           "optional": true,
@@ -22439,14 +22739,14 @@
           "abstract": true,
           "docs": {
             "default": "- the source is staged verbatim, with no build step",
-            "remarks": "Core ships no bundler; implement `IAssetBundler` or use one from a bundler\npackage. Under the default `SOURCE` hashing the build is deferred to synth\nand stays skippable; `OUTPUT` hashing builds eagerly to hash the artifact.\n`AssetType.FILE` is rejected, since bundler output is always a directory.\nSee `AssetStagingOptions.bundler`.",
+            "remarks": "Core ships no bundler; implement `IAssetBundler` or use one from a bundler\npackage. Under the default `SOURCE` hashing the build is deferred to synth\nand stays skippable; `OUTPUT` hashing builds eagerly to hash the artifact.\nThe bundler's output shape must match `type`. See\n`AssetStagingOptions.bundler`.",
             "stability": "experimental",
             "summary": "A bundler that builds the source into an artifact before staging."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 73
+            "line": 75
           },
           "name": "bundler",
           "optional": true,
@@ -22465,7 +22765,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 52
+            "line": 54
           },
           "name": "exclude",
           "optional": true,
@@ -22488,7 +22788,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 60
+            "line": 62
           },
           "name": "extraHash",
           "optional": true,
@@ -22504,7 +22804,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 28
+            "line": 30
           },
           "name": "type",
           "optional": true,
@@ -32378,6 +32678,6 @@
       "symbolId": "src/testing/matchers:TerraformConstructor"
     }
   },
-  "version": "0.25.0-pre.39",
-  "fingerprint": "Mm8DFV8p3EqPwv9VKU0HHSxr3LzTcN0VloMAb2Daxx0="
+  "version": "0.25.0-pre.40",
+  "fingerprint": "lR7vQ8gGX2mBVajufxSJpn696SpU1DOPGaPmPp7v32k="
 }