@fjall/components-infrastructure 33.0.0 → 33.1.0

package/README.md

@@ -54,84 +54,23 @@ for each of the two secrets.
 
 ## Useful commands
 
-- `npm run build` compile typescript to js
-- `npm run watch` watch for changes and compile
-- `npm run test` perform the jest unit tests
-- `cdk deploy` deploy this stack to your default AWS account/region
-- `cdk diff` compare deployed stack with current state
-- `cdk synth` emits the synthesized CloudFormation template
+- `npm run build` — clean, bundle the Lambda assets and compile TypeScript to `dist/`
+- `npm run watch` — recompile on change
+- `npm test` — run the Vitest suites
+- `npm run typecheck` — type-check the library
 
-## Building patterns
+Synthesis and deployment go through the `fjall` CLI (`fjall deploy`), which
+assembles the stacks from an application's `fjall/` directory. The package is
+not deployed with `cdk deploy` on its own.
 
-Common service patterns are built using a Stack class (i.e AwsStack) and use a builder pattern.
+## Using the constructs
 
-### Referencing VPC
+The constructs are consumed through the `fjall` CLI: `fjall create app` and
+`fjall add <resource>` write the `infrastructure.ts` that composes them, and
+`fjall deploy` synthesises and deploys it. Every construct is also exported
+from the package root for direct use; the reference lives at
+[docs.fjall.io](https://docs.fjall.io).
 
-There are three main ways to reference a VPC
+## Licence
 
-1. In the same stack
-
-When a VPC is created in the same stack resources that rely on it will automatically detect it.
-
-```typescript
-new AwsStack(`${id}App`)
-  .addNetwork(FjallVpc.build(`${id}Vpc`))
-  .addConstruct(Fargate.build(`${id}Fargate`));
-```
-
-2. In the same CDK Application but different stack
-
-When a VPC is created in the same application, but you want to use separate stacks, you can directly reference the vpc resource itself. This is easily
-retrieved from an awsStack using `awsStack.getNetwork()`.
-
-```typescript
-const vpcStack = new AwsStack(`${id}Network`).addNetwork(
-  FjallVpc.build(`${id}Vpc`)
-);
-
-const newStack = new AwsStack(`${id}Compute`, { dependencies: [vpcStack] })
-  .addNetwork(vpcStack.getNetwork())
-  .addConstruct(Fargate.build(`${id}Fargate`));
-```
-
-3. Different CDK Applications
-
-If your VPC was created in a completely separate CDK Stack it can be imported using it's `id` and `stackName`. However this method
-requires you explicitly configure your `AwsStack` with an `account` and `region.
-
-```typescript
-const env = {
-  region: "us-east-1",
-  account: "123456789012"
-};
-
-const vpcStack = new AwsStack(`${id}Network`, { ...env }).addNetwork(
-  FjallVpc.build(`${id}Vpc`)
-);
-
-const newStack = new AwsStack(`${id}Compute`, {
-  ...env,
-  dependencies: [vpcStack]
-})
-  .addNetwork(FjallVpc.import(`${id}Vpc`, `${id}Network`))
-  .addConstruct(Fargate.build(`${id}Fargate`));
-```
-
-## Publishing package to npm
-
-Log into your NPM account locally (make sure you have 2fa setup before trying this)
-
-```
-npm login
-> Username:
-> Password
-> Email
-> 2Fa
-```
-
-Update the version in ./package.json, build the package and then run publish command
-
-```
-npm run build
-npm publish --access restricted
-```
+Proprietary — see [LICENSE](./LICENSE).

package/dist/lib/app.d.ts

@@ -311,7 +311,7 @@ export declare class App extends CdkApp {
     addDevSubstrate(props: IDevSubstrateProps): DevSubstrate;
     /**
      * Instantiate the self-hosted Buildkite agent fleet on the default compute
-     * stack (design `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`).
+     * stack (design: the 2026-07-18 Buildkite self-hosted agents design).
      *
      * Same placement contract as `addDevSubstrate` above: deploy-core selects
      * stacks by the fixed six-category enum, so scoping under

package/dist/lib/config/aws/identityCentreConfig.d.ts

@@ -4,7 +4,7 @@ import { type DefaultPermissionSetName } from "@fjall/generator";
  * construct. The discriminated union on `source` mirrors AWS ground truth:
  * the identity source of an Identity Center instance is neither readable nor
  * settable via any supported API, so the mode is user-declared and
- * authoritative. Design: aiDocs/designs/2026-07-04-org-user-management-design.md
+ * authoritative. Design: the 2026-07-04 organisation user-management design.
  *
  * The source vocabulary is canonical in @fjall/generator
  * (organisationSchemas.ts) — re-exported here so existing consumers keep

package/dist/lib/config/aws/identityCentreConfig.js

@@ -5,7 +5,7 @@ import { stripAndCamelCase } from "../../utils/stripAndCamelCase.js";
  * construct. The discriminated union on `source` mirrors AWS ground truth:
  * the identity source of an Identity Center instance is neither readable nor
  * settable via any supported API, so the mode is user-declared and
- * authoritative. Design: aiDocs/designs/2026-07-04-org-user-management-design.md
+ * authoritative. Design: the 2026-07-04 organisation user-management design.
  *
  * The source vocabulary is canonical in @fjall/generator
  * (organisationSchemas.ts) — re-exported here so existing consumers keep

package/dist/lib/config/aws/scpPreset.js

@@ -140,8 +140,7 @@ function buildFoundationGuardrails(allowedRegions) {
                 // assume-root sessions) are deliberately NOT carved out — recovery on
                 // this tier is a break-glass SCP detach, not a standing carve-out. Do
                 // not add them without revisiting the decision:
-                // aiDocs/troubleshooting/centralised-root-access-break-glass-runbook.md
-                // § Scenario 3.
+                // the centralised root-access break-glass runbook, § Scenario 3.
                 NotAction: [
                     "s3:GetBucketPolicy",
                     "s3:PutBucketPolicy",

package/dist/lib/lambda-assets/cert-generator/asset/index.js

@@ -18117,3 +18117,129 @@ exports.handler = async (event) => {
     Data: { CaCertSha256: caCertSha256 }
   };
 };
+/*! Bundled license information:
+
+reflect-metadata/Reflect.js:
+  (*! *****************************************************************************
+  Copyright (C) Microsoft. All rights reserved.
+  Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+  this file except in compliance with the License. You may obtain a copy of the
+  License at http://www.apache.org/licenses/LICENSE-2.0
+  
+  THIS CODE IS PROVIDED ON AN *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED
+  WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,
+  MERCHANTABLITY OR NON-INFRINGEMENT.
+  
+  See the Apache Version 2.0 License for specific language governing permissions
+  and limitations under the License.
+  ***************************************************************************** *)
+
+pvtsutils/build/index.js:
+  (*!
+   * MIT License
+   * 
+   * Copyright (c) 2017-2024 Peculiar Ventures, LLC
+   * 
+   * Permission is hereby granted, free of charge, to any person obtaining a copy
+   * of this software and associated documentation files (the "Software"), to deal
+   * in the Software without restriction, including without limitation the rights
+   * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+   * copies of the Software, and to permit persons to whom the Software is
+   * furnished to do so, subject to the following conditions:
+   * 
+   * The above copyright notice and this permission notice shall be included in all
+   * copies or substantial portions of the Software.
+   * 
+   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+   * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+   * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+   * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+   * SOFTWARE.
+   * 
+   *)
+
+pvutils/build/utils.js:
+  (*!
+   Copyright (c) Peculiar Ventures, LLC
+  *)
+
+asn1js/build/index.js:
+  (*!
+   * Copyright (c) 2014, GMO GlobalSign
+   * Copyright (c) 2015-2022, Peculiar Ventures
+   * All rights reserved.
+   * 
+   * Author 2014-2019, Yury Strozhevsky
+   * 
+   * Redistribution and use in source and binary forms, with or without modification,
+   * are permitted provided that the following conditions are met:
+   * 
+   * * Redistributions of source code must retain the above copyright notice, this
+   *   list of conditions and the following disclaimer.
+   * 
+   * * Redistributions in binary form must reproduce the above copyright notice, this
+   *   list of conditions and the following disclaimer in the documentation and/or
+   *   other materials provided with the distribution.
+   * 
+   * * Neither the name of the copyright holder nor the names of its
+   *   contributors may be used to endorse or promote products derived from
+   *   this software without specific prior written permission.
+   * 
+   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+   * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+   * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+   * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+   * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+   * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+   * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+   * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+   * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+   * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+   * 
+   *)
+
+tslib/tslib.es6.js:
+  (*! *****************************************************************************
+  Copyright (c) Microsoft Corporation.
+  
+  Permission to use, copy, modify, and/or distribute this software for any
+  purpose with or without fee is hereby granted.
+  
+  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+  REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+  AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+  LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+  OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+  PERFORMANCE OF THIS SOFTWARE.
+  ***************************************************************************** *)
+
+@peculiar/x509/build/x509.cjs.js:
+  (*!
+   * MIT License
+   * 
+   * Copyright (c) Peculiar Ventures. All rights reserved.
+   * 
+   * Permission is hereby granted, free of charge, to any person obtaining a copy
+   * of this software and associated documentation files (the "Software"), to deal
+   * in the Software without restriction, including without limitation the rights
+   * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+   * copies of the Software, and to permit persons to whom the Software is
+   * furnished to do so, subject to the following conditions:
+   * 
+   * The above copyright notice and this permission notice shall be included in all
+   * copies or substantial portions of the Software.
+   * 
+   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+   * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+   * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+   * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+   * SOFTWARE.
+   * 
+   *)
+*/

package/dist/lib/patterns/aws/buildkite/buildkite.d.ts

@@ -14,7 +14,7 @@ export type BuildkiteConstructProps = BuildkitePropsInput & {
  * Self-hosted Buildkite agent fleet on the pinned Elastic CI Stack AMIs —
  * scale-to-zero ASG + buildkite-agent-scaler, no secret ever transiting
  * synth, allowlist-only instance IAM. Design:
- * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`.
+ * the 2026-07-18 Buildkite self-hosted agents design.
  *
  * A Construct, not a Stack: instantiate via `App.addBuildkite(props)`, which
  * scopes it under the default compute stack so deploy-core's fixed

package/dist/lib/patterns/aws/buildkite/buildkite.js

@@ -21,7 +21,7 @@ import { buildBuildkiteUserData } from "./userData.js";
  * Self-hosted Buildkite agent fleet on the pinned Elastic CI Stack AMIs —
  * scale-to-zero ASG + buildkite-agent-scaler, no secret ever transiting
  * synth, allowlist-only instance IAM. Design:
- * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`.
+ * the 2026-07-18 Buildkite self-hosted agents design.
  *
  * A Construct, not a Stack: instantiate via `App.addBuildkite(props)`, which
  * scopes it under the default compute stack so deploy-core's fixed

package/dist/lib/patterns/aws/buildkite/factory.d.ts

@@ -5,8 +5,8 @@ import type { BuildkitePropsInput } from "./schema.js";
 /**
  * Thunk returned by `BuildkiteFactory.build` — materialised only by
  * `App.addBuildkite`, which owns stack placement (the fleet has exactly one
- * legal home, `${stackPrefix}Compute`; design
- * `aiDocs/designs/2026-07-18-fjall-add-buildkite.md` § D2).
+ * legal home, `${stackPrefix}Compute`; design:
+ * the 2026-07-18 `fjall add buildkite` design, § D2).
  */
 export type BuildkiteFactoryFn = (app: App, scope: Construct) => Buildkite;
 /**

package/dist/lib/patterns/aws/buildkite/pins.d.ts

@@ -4,7 +4,7 @@
  * release. AMI ids, the elastic-stack version, the scaler version and the
  * secrets-plugin floor MUST only change together, regenerated from the
  * upstream template for the new version (runbook:
- * `aiDocs/runbooks/buildkite-stack-bump-runbook.md`).
+ * the Buildkite stack-bump runbook).
  *
  * AMI ids come from the `Mappings.AWSRegion2AMI` block of
  * `https://s3.amazonaws.com/buildkite-aws-stack/<version>/aws-stack.yml` and
@@ -18,7 +18,7 @@
  * floats the AMI underneath a pinned stack version, needs lookup credentials
  * at synth time (unavailable in worker synth), and makes synth
  * non-deterministic. Design:
- * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md` § D2.
+ * the 2026-07-18 Buildkite self-hosted agents design, § D2.
  */
 export declare const BUILDKITE_AMI_OWNER_ACCOUNT_ID = "172840064832";
 export declare const BUILDKITE_CPU_ARCHITECTURES: readonly ["arm64", "amd64"];

package/dist/lib/patterns/aws/buildkite/pins.js

@@ -4,7 +4,7 @@
  * release. AMI ids, the elastic-stack version, the scaler version and the
  * secrets-plugin floor MUST only change together, regenerated from the
  * upstream template for the new version (runbook:
- * `aiDocs/runbooks/buildkite-stack-bump-runbook.md`).
+ * the Buildkite stack-bump runbook).
  *
  * AMI ids come from the `Mappings.AWSRegion2AMI` block of
  * `https://s3.amazonaws.com/buildkite-aws-stack/<version>/aws-stack.yml` and
@@ -18,7 +18,7 @@
  * floats the AMI underneath a pinned stack version, needs lookup credentials
  * at synth time (unavailable in worker synth), and makes synth
  * non-deterministic. Design:
- * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md` § D2.
+ * the 2026-07-18 Buildkite self-hosted agents design, § D2.
  */
 export const BUILDKITE_AMI_OWNER_ACCOUNT_ID = "172840064832";
 export const BUILDKITE_CPU_ARCHITECTURES = ["arm64", "amd64"];

package/dist/lib/patterns/aws/buildkite/schema.d.ts

@@ -2,7 +2,7 @@
  * Buildkite props schema — re-export barrel. The canonical declaration lives
  * in `@fjall/generator` (`src/schemas/buildkiteSchemas.ts`) so construct
  * validation, the codemod fragment, and the LLM JSON schema all consume one
- * source (design `aiDocs/designs/2026-07-18-fjall-add-buildkite.md` § D4).
+ * source (design: the 2026-07-18 `fjall add buildkite` design, § D4).
  * Do NOT redeclare here — the cross-package reference-identity test pins it.
  */
 export { BuildkitePropsObjectSchema, BuildkitePropsSchema, validateBuildkiteProps, type BuildkiteProps, type BuildkitePropsInput, type BuildkitePropsObject } from "@fjall/generator";

package/dist/lib/patterns/aws/buildkite/schema.js

@@ -2,7 +2,7 @@
  * Buildkite props schema — re-export barrel. The canonical declaration lives
  * in `@fjall/generator` (`src/schemas/buildkiteSchemas.ts`) so construct
  * validation, the codemod fragment, and the LLM JSON schema all consume one
- * source (design `aiDocs/designs/2026-07-18-fjall-add-buildkite.md` § D4).
+ * source (design: the 2026-07-18 `fjall add buildkite` design, § D4).
  * Do NOT redeclare here — the cross-package reference-identity test pins it.
  */
 export { BuildkitePropsObjectSchema, BuildkitePropsSchema, validateBuildkiteProps } from "@fjall/generator";

package/dist/lib/patterns/aws/buildkite/userData.d.ts

@@ -29,7 +29,7 @@ export interface BuildkiteUserDataContext {
  * vendored template in both directions: a key we emit that upstream does not
  * pass is silently ignored; a key upstream passes that we omit is the
  * boot-loop. Bumping the pins regenerates the fixture
- * (runbook: `aiDocs/runbooks/buildkite-stack-bump-runbook.md`).
+ * (runbook: the Buildkite stack-bump runbook).
  */
 export declare const BUILDKITE_MOUNT_PART_ENV_KEYS: readonly ["BUILDKITE_ENABLE_INSTANCE_STORAGE", "BUILDKITE_MOUNT_TMPFS_AT_TMP"];
 export declare const BUILDKITE_DOCKER_PART_ENV_KEYS: readonly ["DOCKER_USERNS_REMAP", "DOCKER_EXPERIMENTAL", "DOCKER_PRUNE_UNTIL", "ENABLE_PRE_EXIT_DISK_CLEANUP", "DOCKER_BUILDER_PRUNE_ENABLED", "DOCKER_NETWORKING_PROTOCOL", "DOCKER_IPV4_ADDRESS_POOL_1", "DOCKER_IPV4_ADDRESS_POOL_2", "DOCKER_IPV6_ADDRESS_POOL", "DOCKER_FIXED_CIDR_V4", "DOCKER_FIXED_CIDR_V6", "BUILDKITE_ENABLE_INSTANCE_STORAGE"];

package/dist/lib/patterns/aws/buildkite/userData.js

@@ -10,7 +10,7 @@ import { BUILDKITE_STACK_PINS } from "./pins.js";
  * vendored template in both directions: a key we emit that upstream does not
  * pass is silently ignored; a key upstream passes that we omit is the
  * boot-loop. Bumping the pins regenerates the fixture
- * (runbook: `aiDocs/runbooks/buildkite-stack-bump-runbook.md`).
+ * (runbook: the Buildkite stack-bump runbook).
  */
 export const BUILDKITE_MOUNT_PART_ENV_KEYS = [
     "BUILDKITE_ENABLE_INSTANCE_STORAGE",

package/dist/lib/patterns/aws/buildkite.d.ts

@@ -2,7 +2,7 @@
  * Self-hosted Buildkite agent fleet — barrel for the `buildkite/` modules.
  * The pre-2026-07 `Buildkite extends Stack` implementation is replaced by a
  * Construct instantiated via `App.addBuildkite()`; design:
- * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`.
+ * the 2026-07-18 Buildkite self-hosted agents design.
  */
 export { AGENT_TOKEN_SECRET_NAME, BUILDKITE_SECRETS_CLUSTER, Buildkite, FJALL_API_KEY_SECRET_NAME, FJALL_ENV_HOOK_OBJECT_KEY, buildAgentSecretsEnvHookScript, type AgentSecretsEnvHookOptions, type BuildkiteConstructProps } from "./buildkite/buildkite.js";
 export { BUILDKITE_AMI_OWNER_ACCOUNT_ID, BUILDKITE_CPU_ARCHITECTURES, BUILDKITE_STACK_PINS, resolvePinnedAmiId, resolveScalerSarApplicationArn, type BuildkiteCpuArchitecture } from "./buildkite/pins.js";

package/dist/lib/patterns/aws/buildkite.js

@@ -2,7 +2,7 @@
  * Self-hosted Buildkite agent fleet — barrel for the `buildkite/` modules.
  * The pre-2026-07 `Buildkite extends Stack` implementation is replaced by a
  * Construct instantiated via `App.addBuildkite()`; design:
- * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`.
+ * the 2026-07-18 Buildkite self-hosted agents design.
  */
 export { AGENT_TOKEN_SECRET_NAME, BUILDKITE_SECRETS_CLUSTER, Buildkite, FJALL_API_KEY_SECRET_NAME, FJALL_ENV_HOOK_OBJECT_KEY, buildAgentSecretsEnvHookScript } from "./buildkite/buildkite.js";
 export { BUILDKITE_AMI_OWNER_ACCOUNT_ID, BUILDKITE_CPU_ARCHITECTURES, BUILDKITE_STACK_PINS, resolvePinnedAmiId, resolveScalerSarApplicationArn } from "./buildkite/pins.js";

package/dist/lib/patterns/aws/clickhouseDatabase.js

@@ -381,7 +381,10 @@ export class ClickHouseDatabase extends Construct {
         const coldTierBucket = coldTierEnabled
             ? (props.coldTierBucket ??
                 new S3Bucket(this, "ClickHouseColdTierBucket", {
-                    versioned: false
+                    // Tiered table parts, re-tiered from hot storage — versioning would
+                    // only bill for churn; the exemption stamp tells posture so.
+                    versioned: false,
+                    versioningExemption: "cold-tier"
                 }))
             : undefined;
         this.#backupBucket = backupBucket;

package/dist/lib/patterns/aws/clickhouseTls/types.d.ts

@@ -17,7 +17,7 @@ export interface ClickHouseSelfSignedTls {
  * supplied the construct surfaces it as a CFN env-var token so consumers
  * can wire it into containers for rotation-triggers-task-replacement
  * parity with self-signed mode. Omit it and rotation requires manual task
- * restart (documented in `aiDocs/patterns/clickhouse-tls-pattern.md § "Imported mode"`).
+ * restart (documented in the ClickHouse TLS pattern, § "Imported mode").
  */
 export interface ClickHouseImportedTls {
     readonly mode: "imported";

package/dist/lib/patterns/aws/computeEcsTypes.d.ts

@@ -182,8 +182,8 @@ export interface EcsContainerConfig {
  *   per service. Suitable for high-replica services where the init-container
  *   tax dominates rollout time.
  *
- * @see aiDocs/decisions/2026-04-29-ecs-init-container-over-runtask.md
- * @see aiDocs/plans/2026-04-29-ecs-factory-hardening.md § 4.3.4 — threshold
+ * @see the 2026-04-29 decision: ECS init container over RunTask
+ * @see the 2026-04-29 ECS factory-hardening plan, § 4.3.4 — threshold
  *   guidance for choosing between modes.
  * @see https://aws.amazon.com/blogs/containers/announcing-amazon-ecs-deployment-lifecycle-hooks/
  */
@@ -223,7 +223,7 @@ export type EcsMigrationsMode = "init-container" | "lifecycle-hook" | "post-depl
  *   mode: "lifecycle-hook"
  * }
  *
- * @see aiDocs/decisions/2026-04-29-ecs-init-container-over-runtask.md
+ * @see the 2026-04-29 decision: ECS init container over RunTask
  */
 /**
  * Discriminated on `mode`. The init-container variant keeps its narrow surface
@@ -237,8 +237,8 @@ export type EcsMigrationsMode = "init-container" | "lifecycle-hook" | "post-depl
  * lifecycle-hook-only field — is a typecheck error. This protects against
  * the Pitfall-5 trap (silent field drift across union variants).
  *
- * @see aiDocs/designs/2026-05-12-migration-runner-abstraction-choice.md
- * @see .claude/rules/typescript-standards.md § "Pitfall 5"
+ * @see the 2026-05-12 migration-runner abstraction-choice design
+ * @see the TypeScript standards, Zod Pitfall 5 (three-way option drift)
  */
 export type EcsMigrationsConfig = EcsInitContainerMigrationsConfig | EcsLifecycleHookMigrationsConfig | EcsPostDeployMigrationsConfig;
 /**

package/dist/lib/patterns/aws/payload.js

@@ -217,8 +217,10 @@ export class Payload extends Construct {
     createAssetsBucket() {
         const assetsConfig = this.props.storage?.assets ?? {};
         const assetsProps = {
-            // Build output, pruned on every deploy — versioning would only bill for churn.
+            // Build output, pruned on every deploy — versioning would only bill for
+            // churn; the exemption stamp tells posture the omission is by design.
             versioned: assetsConfig.versioned ?? false,
+            versioningExemption: "build-output",
             deployment: {
                 source: `${PAYLOAD_DEFAULTS.SOURCE}/${PAYLOAD_DEFAULTS.OPENNEXT.ASSETS}`,
                 prune: true,
@@ -233,8 +235,10 @@ export class Payload extends Construct {
     createCacheBucket() {
         const cacheConfig = this.props.storage?.cache ?? {};
         const cacheProps = {
-            // ISR cache, regenerated at runtime — versioning would only bill for churn.
+            // ISR cache, regenerated at runtime — versioning would only bill for
+            // churn; the exemption stamp tells posture the omission is by design.
             versioned: cacheConfig.versioned ?? false,
+            versioningExemption: "isr-cache",
             deployment: {
                 source: `${PAYLOAD_DEFAULTS.SOURCE}/${PAYLOAD_DEFAULTS.OPENNEXT.CACHE}`,
                 prune: false // ISR adds files at runtime

package/dist/lib/patterns/aws/storage.d.ts

@@ -2,6 +2,7 @@ import { Construct } from "constructs";
 import { type EventType, type IBucketNotificationDestination, type NotificationKeyFilter } from "aws-cdk-lib/aws-s3";
 import { type IDistribution } from "aws-cdk-lib/aws-cloudfront";
 import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
+import { type S3VersioningExemption } from "@fjall/util/aws";
 import type App from "../../app.js";
 import { BucketDeployment, S3Bucket, type ResourcePolicyStatement, type WebsiteHostingConfig } from "../../resources/aws/storage/index.js";
 import { type BackupTier } from "../../utils/backupTierMapping.js";
@@ -39,6 +40,13 @@ export interface S3Props {
      * `resilient`/`enterprise`, off otherwise. An explicit value always wins.
      */
     readonly versioned?: boolean;
+    /**
+     * Why this bucket runs unversioned by design (`build-output`, `isr-cache`,
+     * `cold-tier`) — see `S3BucketProps.versioningExemption`. Stamped as the
+     * `fjall:s3:versioning-exempt` tag when versioning resolves off; a bucket
+     * that versions after all is not stamped.
+     */
+    readonly versioningExemption?: S3VersioningExemption;
     readonly encryption?: "AES256" | "KMS";
     readonly kmsKeyArn?: string;
     /**

package/dist/lib/patterns/aws/storage.js

@@ -78,6 +78,7 @@ export class Storage extends Construct {
             aliasTargetName: props.bucketName ?? id,
             appName: props.appName,
             versioned: props.versioned,
+            versioningExemption: props.versioningExemption,
             encryption: toBucketEncryption(props.encryption),
             encryptionKey,
             ...(props.bucketKeyEnabled !== undefined && {

package/dist/lib/resources/aws/cdn/responseHeadersPolicy.d.ts

@@ -40,7 +40,7 @@ export interface SecurityHeadersPolicyProps {
  * Wrapped on the description + SOC2-defaults trigger (NOT taggability — the
  * resource is not taggable): it owns Fjall's uniform security-header defaults
  * so every consumer inherits the same posture in one edit. Per
- * `.claude/rules/generator-standards.md § Wrapper Routing Discipline`,
+ * the Wrapper Routing Discipline rule (generator standards),
  * `lib/{config,patterns}/` instantiate this class, never the raw L2.
  *
  * Defaults (all `override:true`): HSTS 730d+includeSubdomains+preload,

package/dist/lib/resources/aws/cdn/responseHeadersPolicy.js

@@ -18,7 +18,7 @@ const DEFAULT_COMMENT = "Fjall security headers policy";
  * Wrapped on the description + SOC2-defaults trigger (NOT taggability — the
  * resource is not taggable): it owns Fjall's uniform security-header defaults
  * so every consumer inherits the same posture in one edit. Per
- * `.claude/rules/generator-standards.md § Wrapper Routing Discipline`,
+ * the Wrapper Routing Discipline rule (generator standards),
  * `lib/{config,patterns}/` instantiate this class, never the raw L2.
  *
  * Defaults (all `override:true`): HSTS 730d+includeSubdomains+preload,

package/dist/lib/resources/aws/compute/ec2.d.ts

@@ -27,7 +27,7 @@ export type Ec2InstancePersistentDataVolumeConfig = Omit<PersistentDataVolumePro
  *   `AutoScalingScheduledAction.IgnoreUnmodifiedGroupSizeProperties`
  *   regardless. For callers owning rollout externally.
  *
- * See `aiDocs/troubleshooting/clickhouse-rolling-update-window.md` for the
+ * See the ClickHouse rolling-update-window troubleshooting note for the
  * ClickHouse-specific downtime expectations.
  */
 export type Ec2InstanceUpdatePolicyConfig = {
@@ -127,7 +127,7 @@ export interface Ec2InstanceProps extends StackProps {
      * ASG `UpdatePolicy` resolution. Absent → `UpdatePolicy.instanceRefresh`
      * (0/100 with `persistentDataVolume`, 100/200 otherwise). See
      * `Ec2InstanceUpdatePolicyConfig` for the variant menu and
-     * `aiDocs/troubleshooting/clickhouse-rolling-update-window.md` for the
+     * the ClickHouse rolling-update-window troubleshooting note for the
      * downtime-window runbook.
      */
     updatePolicy?: Ec2InstanceUpdatePolicyConfig;

package/dist/lib/resources/aws/compute/ec2.js

@@ -17,7 +17,7 @@ import { PersistentDataVolume } from "./persistentDataVolume.js";
  * `encrypted: true` enforces EBS encryption at the wrapper layer rather than
  * relying on the AWS account-level "encryption by default" setting — the
  * propagation contract documented in
- * `.claude/rules/generator-standards.md § "Wrapper Routing Discipline"`.
+ * the Wrapper Routing Discipline rule (generator standards).
  */
 const DEFAULT_ROOT_DEVICE_NAME = "/dev/xvda";
 const DEFAULT_ROOT_VOLUME_SIZE_GIB = 30;

package/dist/lib/resources/aws/database/clickhouseConstants.d.ts

@@ -155,7 +155,7 @@ export declare const CLICKHOUSE_NATIVE_PORT = 9000;
 export declare const CLICKHOUSE_PROMETHEUS_PORT = 9363;
 /** TLS-mode ClickHouse ports.
  *  HTTPS replaces 8123; secure native protocol replaces 9000.
- *  See aiDocs/patterns/clickhouse-tls-pattern.md § "The contract". */
+ *  See the ClickHouse TLS pattern, § "The contract". */
 export declare const CLICKHOUSE_HTTPS_PORT = 8443;
 export declare const CLICKHOUSE_TCP_SECURE_PORT = 9440;
 /** Mount path inside the ClickHouse container for the materialised TLS cert
@@ -188,8 +188,8 @@ export declare function clickHouseUserSecretName(userName: string): string;
  *  Canonical source is `@fjall/util/migration § userPasswordEnvName` — re-exported
  *  here so the construct-side import chain stays unchanged while the runner
  *  (`webapp/scripts/migration-runner.mjs`) and any future consumer share a single
- *  declaration. Coupled values per `.claude/rules/code-quality.md § "Coupled values:
- *  shared source at 2 occurrences"`. */
+ *  declaration. Coupled values (the shared-source-at-two-occurrences
+ *  rule). */
 export { userPasswordEnvName } from "@fjall/util/migration";
 /** Env var name carrying the SHA-256 of a user's plaintext password.
  *  The container entrypoint wrapper derives this name from the
@@ -305,8 +305,8 @@ export declare const BACKUP_RETENTION_DAYS = 14;
  *  wrote can be read back. Dropped on the way in and on the way out; never
  *  queried by the application. Canonical source is `@fjall/util/migration`
  *  because `@fjall/clickhouse` grants `fjall_maintenance` DROP on exactly
- *  this database — coupled values per `.claude/rules/code-quality.md §
- *  "Coupled values: shared source at 2 occurrences"`. */
+ *  this database — coupled values (the shared-source-at-two-occurrences
+ *  rule). */
 export { CLICKHOUSE_BACKUP_SCRATCH_DATABASE } from "@fjall/util/migration";
 /** The two scheduled maintenance jobs that authenticate as
  *  `fjall_maintenance`. Drives the per-job log-group → metric-filter wiring

package/dist/lib/resources/aws/database/clickhouseConstants.js

@@ -175,7 +175,7 @@ export const CLICKHOUSE_NATIVE_PORT = 9000;
 export const CLICKHOUSE_PROMETHEUS_PORT = 9363;
 /** TLS-mode ClickHouse ports.
  *  HTTPS replaces 8123; secure native protocol replaces 9000.
- *  See aiDocs/patterns/clickhouse-tls-pattern.md § "The contract". */
+ *  See the ClickHouse TLS pattern, § "The contract". */
 export const CLICKHOUSE_HTTPS_PORT = 8443;
 export const CLICKHOUSE_TCP_SECURE_PORT = 9440;
 /** Mount path inside the ClickHouse container for the materialised TLS cert
@@ -210,8 +210,8 @@ export function clickHouseUserSecretName(userName) {
  *  Canonical source is `@fjall/util/migration § userPasswordEnvName` — re-exported
  *  here so the construct-side import chain stays unchanged while the runner
  *  (`webapp/scripts/migration-runner.mjs`) and any future consumer share a single
- *  declaration. Coupled values per `.claude/rules/code-quality.md § "Coupled values:
- *  shared source at 2 occurrences"`. */
+ *  declaration. Coupled values (the shared-source-at-two-occurrences
+ *  rule). */
 export { userPasswordEnvName } from "@fjall/util/migration";
 /** Env var name carrying the SHA-256 of a user's plaintext password.
  *  The container entrypoint wrapper derives this name from the
@@ -347,8 +347,8 @@ export const BACKUP_RETENTION_DAYS = 14;
  *  wrote can be read back. Dropped on the way in and on the way out; never
  *  queried by the application. Canonical source is `@fjall/util/migration`
  *  because `@fjall/clickhouse` grants `fjall_maintenance` DROP on exactly
- *  this database — coupled values per `.claude/rules/code-quality.md §
- *  "Coupled values: shared source at 2 occurrences"`. */
+ *  this database — coupled values (the shared-source-at-two-occurrences
+ *  rule). */
 export { CLICKHOUSE_BACKUP_SCRATCH_DATABASE } from "@fjall/util/migration";
 /** The two scheduled maintenance jobs that authenticate as
  *  `fjall_maintenance`. Drives the per-job log-group → metric-filter wiring

package/dist/lib/resources/aws/iam/identityCenter/user.d.ts

@@ -8,7 +8,7 @@ export interface IdentityStoreUserProviderProps {
  * Shared Provider-framework backend for Custom::FjallIdentityStoreUser —
  * one handler + provider pair serves every declared user in the stack. A
  * plain AwsCustomResource cannot express the create-or-adopt branching the
- * handler implements (aiDocs/designs/2026-07-04-org-user-management-design.md § 2).
+ * handler implements (the 2026-07-04 organisation user-management design, § 2).
  */
 export declare class IdentityStoreUserProvider extends Construct {
     readonly serviceToken: string;

package/dist/lib/resources/aws/iam/identityCenter/user.js

@@ -23,7 +23,7 @@ export function identityStoreUserArnPattern(partition) {
  * Shared Provider-framework backend for Custom::FjallIdentityStoreUser —
  * one handler + provider pair serves every declared user in the stack. A
  * plain AwsCustomResource cannot express the create-or-adopt branching the
- * handler implements (aiDocs/designs/2026-07-04-org-user-management-design.md § 2).
+ * handler implements (the 2026-07-04 organisation user-management design, § 2).
  */
 export class IdentityStoreUserProvider extends Construct {
     serviceToken;

package/dist/lib/resources/aws/storage/bucketDeployment.d.ts

@@ -5,9 +5,8 @@ import { type Construct } from "constructs";
  *
  * Applies one default: an explicit, stack-shared log group for the deployment
  * handler lambda, so it is CloudFormation-managed and tagged rather than
- * service-auto-created. Per `.claude/rules/generator-standards.md § Wrapper
- * Routing Discipline` and
- * `patterns/infrastructure-wrapper-routing-pattern.md § A3`, `lib/{config,
+ * service-auto-created. Per the Wrapper Routing Discipline rule (generator
+ * standards) and the infrastructure wrapper-routing pattern (§ A3), `lib/{config,
  * patterns}/` MUST instantiate this class rather than the raw CDK construct.
  */
 export declare class BucketDeployment extends CdkBucketDeployment {

package/dist/lib/resources/aws/storage/bucketDeployment.js

@@ -5,9 +5,8 @@ import { stackSingletonLogGroup } from "../logging/singletonLogGroup.js";
  *
  * Applies one default: an explicit, stack-shared log group for the deployment
  * handler lambda, so it is CloudFormation-managed and tagged rather than
- * service-auto-created. Per `.claude/rules/generator-standards.md § Wrapper
- * Routing Discipline` and
- * `patterns/infrastructure-wrapper-routing-pattern.md § A3`, `lib/{config,
+ * service-auto-created. Per the Wrapper Routing Discipline rule (generator
+ * standards) and the infrastructure wrapper-routing pattern (§ A3), `lib/{config,
  * patterns}/` MUST instantiate this class rather than the raw CDK construct.
  */
 export class BucketDeployment extends CdkBucketDeployment {

package/dist/lib/resources/aws/storage/s3.d.ts

@@ -1,7 +1,8 @@
+import { type S3VersioningExemption } from "@fjall/util/aws";
 import { Bucket, type BucketProps } from "aws-cdk-lib/aws-s3";
 import { type Construct } from "constructs";
 import { type BackupTier } from "../../../utils/backupTierMapping.js";
-export { SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
+export { S3_VERSIONING_EXEMPT_TAG_KEY, SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
 /**
  * Days a noncurrent object version is retained before lifecycle expiry.
  * The wrapper pairs this automatically when it enables versioning; constructs
@@ -59,6 +60,17 @@ export interface S3BucketProps extends BucketProps {
      * direct `new S3Bucket` construction needs to pass it.
      */
     appBackupTier?: BackupTier;
+    /**
+     * Why this bucket runs unversioned by design. Stamped as the
+     * `fjall:s3:versioning-exempt` tag only when versioning resolves off — a
+     * bucket that versions after all (an explicit `versioned: true`, or a tier
+     * that turns it on) has nothing to exempt — so posture lands the
+     * `S3_VERSIONING_DISABLED` finding `mitigated` rather than `open` on
+     * buckets whose contents are rebuilt, not kept. Constructs pass it for the
+     * buckets they own (Payload build output and ISR cache, ClickHouse cold
+     * tier); an author may pass it for a disposable bucket of their own.
+     */
+    versioningExemption?: S3VersioningExemption;
     publicReadAccess?: boolean;
     websiteHosting?: WebsiteHostingConfig;
     /**

package/dist/lib/resources/aws/storage/s3.js

@@ -1,4 +1,4 @@
-import { SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
+import { S3_VERSIONING_EXEMPT_TAG_KEY, SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
 import { Annotations, CfnOutput, Duration, RemovalPolicy, Tags } from "aws-cdk-lib";
 import { BlockPublicAccess, Bucket, BucketEncryption } from "aws-cdk-lib/aws-s3";
 import { ArnPrincipal, Effect, PolicyStatement, StarPrincipal } from "aws-cdk-lib/aws-iam";
@@ -7,7 +7,7 @@ import { resolveEffectiveBackupTier, shouldAutoVersion } from "../../../utils/ba
 import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { bucketWebsiteEndpointExportName, bucketWebsiteHostedZoneIdExportName } from "@fjall/util";
 import { envAwareRemovalPolicyDefault, toRemovalPolicy } from "../../../utils/removalPolicy.js";
-export { SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
+export { S3_VERSIONING_EXEMPT_TAG_KEY, SDK_PRE_EMPTY_TAG_KEY } from "@fjall/util/aws";
 /**
  * Days a noncurrent object version is retained before lifecycle expiry.
  * The wrapper pairs this automatically when it enables versioning; constructs
@@ -26,7 +26,7 @@ export class S3Bucket extends Bucket {
     /** The tier the bucket runs under: `backupVaultTier`, else `appBackupTier`. */
     effectiveBackupTier;
     constructor(scope, id, props = {}) {
-        const { websiteHosting, backupVaultTier, appBackupTier, resourcePolicyStatements, aliasTargetName, appName, ...cdkProps } = props;
+        const { websiteHosting, backupVaultTier, appBackupTier, resourcePolicyStatements, aliasTargetName, appName, versioningExemption, ...cdkProps } = props;
         const isPublic = props.publicReadAccess === true || websiteHosting !== undefined;
         const effectiveBackupTier = resolveEffectiveBackupTier(backupVaultTier, appBackupTier);
         const versioned = props.versioned ?? shouldAutoVersion(effectiveBackupTier);
@@ -112,6 +112,9 @@ export class S3Bucket extends Bucket {
         if (removalPolicy === RemovalPolicy.DESTROY) {
             Tags.of(this).add(SDK_PRE_EMPTY_TAG_KEY, "true");
         }
+        if (versioningExemption !== undefined && !versioned) {
+            Tags.of(this).add(S3_VERSIONING_EXEMPT_TAG_KEY, versioningExemption);
+        }
         if (websiteHosting) {
             if (appName === undefined) {
                 // Refusing beats falling back to a bucket-only export name: the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "33.0.0",
+  "version": "33.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -41,6 +41,7 @@
     "build:cert-gen-lambda": "node lib/lambda-assets/cert-generator/src/build.mjs",
     "build": "npm run clean && npm run build:cert-gen-lambda && tsc && cp -r lib/layers dist/lib/layers && mkdir -p dist/lib/lambda-assets/cert-generator/asset && cp lib/lambda-assets/cert-generator/asset/index.js dist/lib/lambda-assets/cert-generator/asset/index.js && cp lib/lambda-assets/cert-generator/asset/package.json dist/lib/lambda-assets/cert-generator/asset/package.json && mkdir -p dist/lib/lambda-assets/identity-store-user/asset && cp lib/lambda-assets/identity-store-user/asset/index.js dist/lib/lambda-assets/identity-store-user/asset/index.js && cp lib/lambda-assets/identity-store-user/asset/package.json dist/lib/lambda-assets/identity-store-user/asset/package.json && mkdir -p dist/lib/lambda-assets/static-site-forms/asset && cp lib/lambda-assets/static-site-forms/asset/index.js dist/lib/lambda-assets/static-site-forms/asset/index.js && cp lib/lambda-assets/static-site-forms/asset/package.json dist/lib/lambda-assets/static-site-forms/asset/package.json && cp lib/resources/aws/compute/lifecycleHookLambda.source.cjs dist/lib/resources/aws/compute/lifecycleHookLambda.source.cjs && cp lib/resources/aws/compute/ec2GracefulTerminationLambda.source.cjs dist/lib/resources/aws/compute/ec2GracefulTerminationLambda.source.cjs && cp lib/resources/aws/compute/persistentDataVolumeLambda.source.cjs dist/lib/resources/aws/compute/persistentDataVolumeLambda.source.cjs && cp lib/patterns/aws/devSubstrate.waker.source.cjs dist/lib/patterns/aws/devSubstrate.waker.source.cjs && node ../../scripts/stamp-build.mjs",
     "prepack": "node ../../scripts/check-dist-freshness.mjs",
+    "prepublishOnly": "node ../../scripts/audit-package-tarball.mjs",
     "watch": "tsc -w",
     "watch:only": "tsc -w",
     "test": "vitest run",
@@ -78,8 +79,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1098.0",
-    "@fjall/generator": "^33.0.0",
-    "@fjall/util": "^33.0.0",
+    "@fjall/generator": "^33.1.0",
+    "@fjall/util": "^33.1.0",
     "constructs": "^10.7.2",
     "zod": "^4.4.3"
   },