@fjall/components-infrastructure 4.1.0 → 4.3.0

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

@@ -1,4 +1,5 @@
 import { type GovernancePreset } from "@fjall/generator";
+import { type AccountTier } from "@fjall/util";
 import { Construct } from "constructs";
 export interface OidcConnectorProps {
     fjallOrgId: string;
@@ -19,6 +20,18 @@ export interface OidcConnectorProps {
      * other stage ⇒ deploy role only.
      */
     accountStage?: string;
+    /**
+     * Account TIER of the connected account (organisation | platform | account) —
+     * the structural TIER axis, from the account stack's polymorphic
+     * `deployRoleAccountTier()`; NEVER the wire `environment` / stage axis (that is
+     * `accountStage`). Drives the §4.4a deploy-trust governance expand: a
+     * governance tier (organisation/platform) plus the synth account id widens the
+     * `FjallDeploy` machine subject to ALSO accept the account-scoped literal
+     * `org:{orgId}:acct:{awsAccountId}` (StringEquals array = OR of exact
+     * literals), so per-account deploy issuance can later flip. App-tier
+     * ("account") or absent ⇒ generic-only scalar (unchanged, fail-safe).
+     */
+    accountTier?: AccountTier;
 }
 export declare class OidcConnector extends Construct {
     readonly deployRoleArn: string;

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

@@ -115,10 +115,15 @@ export class OidcConnector extends Construct {
                 statements: SECURITY_TIER_TO_BOUNDARY[props.securityTier].map((statement) => iam.PolicyStatement.fromJson(statement))
             })
             : undefined;
+        // Concrete when env.account is set, a token otherwise — both render. Feeds
+        // the governance-expand machine subject and the dev-tier surface below.
+        const accountId = Stack.of(this).account;
         const trustParams = {
             fjallOrgId: props.fjallOrgId,
             providerArn,
-            issuerDomain
+            issuerDomain,
+            accountId,
+            ...(props.accountTier !== undefined && { accountTier: props.accountTier })
         };
         const deployRole = new Role(this, "DeployRole", {
             roleName: `FjallDeploy${props.fjallOrgId}`,
@@ -141,7 +146,6 @@ export class OidcConnector extends Construct {
         // with the Quick-Create yaml's IsDevelopmentStage-conditional resources
         // and the webapp dev-gate-remediate pass).
         if (props.accountStage === "development") {
-            const accountId = Stack.of(this).account;
             new ManagedPolicy(this, "DevBoundary", {
                 managedPolicyName: DEV_BOUNDARY_POLICY_NAME,
                 description: "Fjall dev-tier permissions boundary — ceiling for the per-slot task roles the dev provisioner creates",

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

@@ -13,6 +13,7 @@ import type { ConfigRecorderProps } from "../../config/aws/configRecorder.js";
 import type { ConfigRulePresetProps } from "../../config/aws/configRulePreset.js";
 import type { OrganisationType } from "./interfaces/organisation.js";
 import { type GovernancePreset } from "@fjall/generator";
+import { type AccountTier } from "@fjall/util";
 export interface AccountProps extends StackProps {
     accountId?: string;
     region?: string;
@@ -47,6 +48,19 @@ export declare class Account extends Stack {
      * independent, and Platform must take one but not the other.
      */
     protected receivesDeployRole(): boolean;
+    /**
+     * Account TIER passed to this account's `OidcConnector` for the §4.4a
+     * deploy-trust governance expand. A polymorphic METHOD, not a read of the
+     * `organisationType` field: the connector is instantiated in THIS base
+     * constructor, and subclass field initialisers run AFTER `super()`, so
+     * `this.organisationType` would read "account" for every subclass here (the
+     * same construction-order reason `receivesDeployRole()` is a method). Base ⇒
+     * "account" (app-tier, generic-only trust); `Platform` ⇒ "platform" and
+     * `Organisation` ⇒ "organisation" override. Governance tiers widen the deploy
+     * machine subject; kept in lockstep with `organisationType` by the
+     * Platform-synth deploy-trust parity test.
+     */
+    protected deployRoleAccountTier(): AccountTier;
     /**
      * Whether this account creates the default-ECR-image helper (the CodeBuild
      * project that seeds a placeholder application image). App-hosting accounts

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

@@ -81,6 +81,7 @@ export class Account extends Stack {
             new OidcConnector(this, "OidcConnector", {
                 fjallOrgId,
                 accountStage: environment,
+                accountTier: this.deployRoleAccountTier(),
                 ...(props.securityTier !== undefined && {
                     securityTier: props.securityTier
                 })
@@ -146,6 +147,21 @@ export class Account extends Stack {
     receivesDeployRole() {
         return this.constructor === Account;
     }
+    /**
+     * Account TIER passed to this account's `OidcConnector` for the §4.4a
+     * deploy-trust governance expand. A polymorphic METHOD, not a read of the
+     * `organisationType` field: the connector is instantiated in THIS base
+     * constructor, and subclass field initialisers run AFTER `super()`, so
+     * `this.organisationType` would read "account" for every subclass here (the
+     * same construction-order reason `receivesDeployRole()` is a method). Base ⇒
+     * "account" (app-tier, generic-only trust); `Platform` ⇒ "platform" and
+     * `Organisation` ⇒ "organisation" override. Governance tiers widen the deploy
+     * machine subject; kept in lockstep with `organisationType` by the
+     * Platform-synth deploy-trust parity test.
+     */
+    deployRoleAccountTier() {
+        return "account";
+    }
     /**
      * Whether this account creates the default-ECR-image helper (the CodeBuild
      * project that seeds a placeholder application image). App-hosting accounts

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

@@ -25,7 +25,7 @@ import { FjallLogger } from "../../utils/validationLogger.js";
 import { VALIDATION_PATTERNS } from "@fjall/generator";
 import { evaluateBakeGuard } from "@fjall/util/docker";
 import { toKebab, buildParameterPath } from "@fjall/util";
-import { validateEcsDomainConfig, validateSecretName } from "../../resources/aws/compute/ecsValidation.js";
+import { validateEc2ServiceSizing, validateEcsDomainConfig, validateSecretName } from "../../resources/aws/compute/ecsValidation.js";
 import { COMPUTE_DEFAULTS, collectImportedSecretNames } from "./compute.js";
 import { isHookMigrations } from "./computeEcsTypes.js";
 export { ScalingType } from "./computeEcsTypes.js";
@@ -150,6 +150,7 @@ export function validateEcsProps(props) {
             FjallLogger.warn(`Service '${service.name}' has ec2Config but capacityProvider is not 'EC2'. ` +
                 "The ec2Config will be ignored unless capacityProvider is set to 'EC2'.");
         }
+        validateEc2ServiceSizing(service);
         if (service.deployment !== undefined) {
             const min = service.deployment.minHealthyPercent;
             const max = service.deployment.maxHealthyPercent;

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

@@ -5,6 +5,7 @@ import { type IdentityCentreConfig } from "../../config/aws/identityCentreConfig
 import { ScpPreset } from "../../config/aws/scpPreset.js";
 import type { ScpPresetProps } from "../../config/aws/scpPreset.js";
 import { OrganisationResource } from "../../resources/aws/organisation/index.js";
+import { type AccountTier } from "@fjall/util";
 export type AccountsConfig = {
     readonly [key: string]: readonly string[] | string | AccountsConfig;
 };
@@ -58,6 +59,14 @@ export declare class Organisation extends Account {
      * gate, so no `OidcConnector` is synthesised on the root stack.
      */
     protected receivesDeployRole(): boolean;
+    /**
+     * Account TIER = organisation (the AWS Organizations management account). The
+     * root never instantiates an `OidcConnector` (`receivesDeployRole()` is false
+     * — its deploy trust is owned by the Quick-Create template), so this override
+     * is not reached on the CDK path today; it keeps `deployRoleAccountTier()`
+     * honest with `organisationType` for any future caller.
+     */
+    protected deployRoleAccountTier(): AccountTier;
     /**
      * The organisation root runs no application workloads, so it needs no
      * default-ECR-image helper.

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

@@ -125,6 +125,16 @@ export class Organisation extends Account {
     receivesDeployRole() {
         return false;
     }
+    /**
+     * Account TIER = organisation (the AWS Organizations management account). The
+     * root never instantiates an `OidcConnector` (`receivesDeployRole()` is false
+     * — its deploy trust is owned by the Quick-Create template), so this override
+     * is not reached on the CDK path today; it keeps `deployRoleAccountTier()`
+     * honest with `organisationType` for any future caller.
+     */
+    deployRoleAccountTier() {
+        return "organisation";
+    }
     /**
      * The organisation root runs no application workloads, so it needs no
      * default-ECR-image helper.

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

@@ -4,6 +4,7 @@ import { type AccountsConfig } from "./organisation.js";
 import { SecurityServicesAdmin } from "../../config/aws/securityServicesAdmin.js";
 import type { SecurityServicesAdminProps } from "../../config/aws/securityServicesAdmin.js";
 import type { OrganisationType } from "./interfaces/organisation.js";
+import { type AccountTier } from "@fjall/util";
 export interface PlatformProps extends AccountProps {
     accounts?: AccountsConfig;
 }
@@ -11,5 +12,6 @@ export declare class Platform extends Account {
     readonly organisationType: OrganisationType;
     constructor(scope: Construct, id: string, props: PlatformProps);
     protected receivesDeployRole(): boolean;
+    protected deployRoleAccountTier(): AccountTier;
     enableSecurityServicesAdmin(props: SecurityServicesAdminProps): SecurityServicesAdmin;
 }

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

@@ -26,6 +26,9 @@ export class Platform extends Account {
     receivesDeployRole() {
         return true;
     }
+    deployRoleAccountTier() {
+        return "platform";
+    }
     enableSecurityServicesAdmin(props) {
         return new SecurityServicesAdmin(this, "SecurityServicesAdmin", props);
     }

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

@@ -214,6 +214,9 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
             stopTimeout: containerConfig.stopTimeout !== undefined
                 ? Duration.seconds(containerConfig.stopTimeout)
                 : undefined,
+            // EC2 container memory is ec2Config-only by design — do NOT add a
+            // `?? serviceProps.memoryLimitMiB` fallback (that is the silent-ignore
+            // footgun `validateEc2ServiceSizing` exists to reject).
             ...(isServiceEc2(serviceProps) && {
                 memoryLimitMiB: serviceProps.ec2Config?.memoryLimitMiB ??
                     DEFAULT_EC2_CONTAINER_MEMORY_MIB

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

@@ -102,7 +102,12 @@ export interface Ec2CapacityConfig {
     minCapacity?: number;
     /** Maximum number of instances. Default: 3 */
     maxCapacity?: number;
-    /** Memory limit in MiB for the container. Default: 1024 */
+    /**
+     * Memory limit in MiB for the container. Default: 1024. This is the ONLY
+     * memory knob for an EC2 service — the service-level `memoryLimitMiB` on
+     * `EcsServiceProps` is Fargate-only and is rejected at synth for EC2 capacity
+     * (see `validateEc2ServiceSizing`).
+     */
     memoryLimitMiB?: number;
     /** Warm pool keeps stopped instances for faster start (10-15s vs 60-90s).
      *  Mirrors generator WarmPool type (generator/src/schemas/computeSchemas.ts). */
@@ -442,9 +447,19 @@ export interface EcsServiceProps {
      * The first container with a port is the **primary container** (receives ALB traffic).
      */
     containers: EcsClusterContainerConfig[];
-    /** CPU units for this service's tasks (256-4096) */
+    /**
+     * CPU units for this service's tasks (256-4096). Fargate only — EC2 task
+     * definitions carry no task-level CPU reservation (CPU is bounded by the
+     * instance type), so a value here is rejected at synth when `capacityProvider`
+     * is 'EC2' (see `validateEc2ServiceSizing`).
+     */
     cpu?: number;
-    /** Memory in MiB for this service's tasks (512-30720) */
+    /**
+     * Memory in MiB for this service's tasks (512-30720). Fargate only — for EC2
+     * capacity the container memory comes from `ec2Config.memoryLimitMiB`; a
+     * service-level value here is rejected at synth unless it exactly mirrors
+     * that field (see `validateEc2ServiceSizing`).
+     */
     memoryLimitMiB?: number;
     /** Desired number of tasks. Default: 2 */
     desiredCount?: number;

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

@@ -1,4 +1,4 @@
-import type { DomainConfig, EcsClusterProps } from "./ecsTypes.js";
+import type { DomainConfig, EcsCapacityProvider, EcsClusterProps } from "./ecsTypes.js";
 /**
  * Validates ECS cluster props before construction.
  * Pure function — does not depend on class state.
@@ -23,6 +23,60 @@ import type { DomainConfig, EcsClusterProps } from "./ecsTypes.js";
  * @throws Error if validation fails
  */
 export declare function validateEcsClusterProps(props: EcsClusterProps): void;
+/**
+ * Minimal structural input for {@link validateEc2ServiceSizing} — exactly the
+ * fields the guard reads. Both the resources-layer `EcsServiceProps` and the
+ * patterns-layer `EcsServiceConfig` structurally satisfy it, so one guard serves
+ * both validation layers without coupling to either full service type
+ * (typescript-standards § "Helpers consume resolved state, not the dispatch enum":
+ * the parameter type is the fields the body actually reads, nothing wider).
+ */
+interface Ec2ServiceSizingInput {
+    name: string;
+    capacityProvider?: EcsCapacityProvider;
+    cpu?: number;
+    memoryLimitMiB?: number;
+    ec2Config?: {
+        memoryLimitMiB?: number;
+    };
+}
+/**
+ * Rejects service-level task sizing that is silently ignored for EC2 capacity.
+ *
+ * For an EC2-capacity ECS service the container's hard memory limit is derived
+ * from `ec2Config.memoryLimitMiB` (default {@link DEFAULT_EC2_CONTAINER_MEMORY_MIB}),
+ * NOT from the service-level `memoryLimitMiB` — that field only feeds the
+ * Fargate task definition (`createTaskDefinition` in `ecsTaskDefinition.ts`: the
+ * EC2 branch passes neither `cpu` nor `memoryLimitMiB`; the container's memory
+ * comes solely from the `ec2Config.memoryLimitMiB ?? default` spread). A
+ * service-level `cpu` has no EC2 analogue at all — EC2 task definitions carry no
+ * task-level CPU reservation and `Ec2CapacityConfig` has no `cpu` field — so it
+ * is always dead on an EC2 service. Both fields read as "size the task to N"
+ * while the deployed container ignores the value.
+ *
+ * Fail loud at synth rather than silently honour the value: silently honouring
+ * memory would rewrite deployed container memory in BOTH directions — raise it
+ * past the EC2 instance's capacity (failure-to-place mid-rollout) or lower it
+ * into the service-level [512,1023] band below the 1024 EC2 default (fresh OOM).
+ * Rejecting changes nothing deployed; it converts two silent misconfigs into a
+ * synth error with a named cure.
+ *
+ * `both-set-and-equal` is allowed for memory — a config that mirrors
+ * `ec2Config.memoryLimitMiB` into the service-level field is self-consistent and
+ * the derived container memory is unchanged. `cpu` has no such carve-out (there
+ * is no `ec2Config.cpu` to agree with); it always throws on EC2.
+ *
+ * Called from BOTH validation layers — resources `validateEcsClusterProps` and
+ * patterns `validateEcsProps` — so the guard cannot drift between them
+ * (code-quality § "Coupled values: shared source at 2 occurrences"; mirrors the
+ * `validateEcsDomainConfig` shared-helper precedent below).
+ *
+ * @param service - The service props to validate (no-op unless EC2 capacity)
+ * @throws Error if an EC2 service carries an ignored service-level `cpu`, or a
+ *   service-level `memoryLimitMiB` that is absent from / conflicts with
+ *   `ec2Config.memoryLimitMiB`
+ */
+export declare function validateEc2ServiceSizing(service: Ec2ServiceSizingInput): void;
 /**
  * Domain-config constraints shared by the resources-layer hook
  * (`validateEcsClusterProps`) and the patterns-layer mirror
@@ -52,3 +106,4 @@ export declare function validateSsmPathComponent(component: string, fieldName: s
  * reference the fjall secrets tooling can never write.
  */
 export declare function validateSecretName(name: string, context: string): void;
+export {};

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

@@ -2,6 +2,7 @@ import { NetworkMode } from "aws-cdk-lib/aws-ecs";
 import { evaluateBakeGuard } from "@fjall/util/docker";
 import { toKebab, SSM_COMPONENT_PATTERN, SSM_COMPONENT_ERROR, SECRET_NAME_PATTERN, SECRET_NAME_ERROR } from "@fjall/util";
 import { ScalingType } from "./ecsTypes.js";
+import { DEFAULT_EC2_CONTAINER_MEMORY_MIB } from "./ecsConstants.js";
 /**
  * Validates ECS cluster props before construction.
  * Pure function — does not depend on class state.
@@ -121,6 +122,7 @@ export function validateEcsClusterProps(props) {
             throw new Error(`Service '${service.name}' uses EC2 capacity provider but no ec2Config is defined. ` +
                 "Provide ec2Config on the service.");
         }
+        validateEc2ServiceSizing(service);
         if (service.deployment !== undefined) {
             const min = service.deployment.minHealthyPercent;
             const max = service.deployment.maxHealthyPercent;
@@ -188,6 +190,70 @@ export function validateEcsClusterProps(props) {
         }
     }
 }
+/**
+ * Rejects service-level task sizing that is silently ignored for EC2 capacity.
+ *
+ * For an EC2-capacity ECS service the container's hard memory limit is derived
+ * from `ec2Config.memoryLimitMiB` (default {@link DEFAULT_EC2_CONTAINER_MEMORY_MIB}),
+ * NOT from the service-level `memoryLimitMiB` — that field only feeds the
+ * Fargate task definition (`createTaskDefinition` in `ecsTaskDefinition.ts`: the
+ * EC2 branch passes neither `cpu` nor `memoryLimitMiB`; the container's memory
+ * comes solely from the `ec2Config.memoryLimitMiB ?? default` spread). A
+ * service-level `cpu` has no EC2 analogue at all — EC2 task definitions carry no
+ * task-level CPU reservation and `Ec2CapacityConfig` has no `cpu` field — so it
+ * is always dead on an EC2 service. Both fields read as "size the task to N"
+ * while the deployed container ignores the value.
+ *
+ * Fail loud at synth rather than silently honour the value: silently honouring
+ * memory would rewrite deployed container memory in BOTH directions — raise it
+ * past the EC2 instance's capacity (failure-to-place mid-rollout) or lower it
+ * into the service-level [512,1023] band below the 1024 EC2 default (fresh OOM).
+ * Rejecting changes nothing deployed; it converts two silent misconfigs into a
+ * synth error with a named cure.
+ *
+ * `both-set-and-equal` is allowed for memory — a config that mirrors
+ * `ec2Config.memoryLimitMiB` into the service-level field is self-consistent and
+ * the derived container memory is unchanged. `cpu` has no such carve-out (there
+ * is no `ec2Config.cpu` to agree with); it always throws on EC2.
+ *
+ * Called from BOTH validation layers — resources `validateEcsClusterProps` and
+ * patterns `validateEcsProps` — so the guard cannot drift between them
+ * (code-quality § "Coupled values: shared source at 2 occurrences"; mirrors the
+ * `validateEcsDomainConfig` shared-helper precedent below).
+ *
+ * @param service - The service props to validate (no-op unless EC2 capacity)
+ * @throws Error if an EC2 service carries an ignored service-level `cpu`, or a
+ *   service-level `memoryLimitMiB` that is absent from / conflicts with
+ *   `ec2Config.memoryLimitMiB`
+ */
+export function validateEc2ServiceSizing(service) {
+    if (service.capacityProvider !== "EC2")
+        return;
+    if (service.memoryLimitMiB !== undefined) {
+        const ec2Memory = service.ec2Config?.memoryLimitMiB;
+        if (ec2Memory === undefined) {
+            throw new Error(`Service '${service.name}': service-level memoryLimitMiB (${service.memoryLimitMiB}) is ignored ` +
+                "for EC2 capacity — the container's hard memory limit comes from ec2Config.memoryLimitMiB " +
+                `(default ${DEFAULT_EC2_CONTAINER_MEMORY_MIB} MiB), not the service-level field. Set ` +
+                `ec2Config.memoryLimitMiB: ${service.memoryLimitMiB} to size the container, or remove the ` +
+                "service-level memoryLimitMiB. (Service-level memoryLimitMiB only applies to Fargate services.)");
+        }
+        if (ec2Memory !== service.memoryLimitMiB) {
+            throw new Error(`Service '${service.name}': conflicting memory limits — service-level memoryLimitMiB ` +
+                `(${service.memoryLimitMiB}) disagrees with ec2Config.memoryLimitMiB (${ec2Memory}). For EC2 ` +
+                "capacity only ec2Config.memoryLimitMiB sizes the container; the service-level value is ignored. " +
+                "Set both to the same value or remove the service-level memoryLimitMiB.");
+        }
+        // both-set-and-equal falls through untouched (allowed): the config is
+        // self-consistent and the derived container memory is unchanged.
+    }
+    if (service.cpu !== undefined) {
+        throw new Error(`Service '${service.name}': service-level cpu (${service.cpu}) is ignored for EC2 capacity — ` +
+            "EC2 task definitions carry no task-level CPU reservation (CPU is bounded by the instance type) " +
+            "and there is no ec2Config.cpu field. Remove the service-level cpu. " +
+            "(Service-level cpu only applies to Fargate services.)");
+    }
+}
 /**
  * Domain-config constraints shared by the resources-layer hook
  * (`validateEcsClusterProps`) and the patterns-layer mirror

package/dist/lib/utils/engineCompat.d.ts

@@ -0,0 +1,37 @@
+import { type EngineCompat } from "@fjall/util/manifest/schemas";
+/**
+ * The constructs' own package version — the assembly's `synthesisedBy`.
+ * `undefined` only when the package layout is broken enough that the upward
+ * walk finds no matching `package.json`.
+ */
+export declare const CONSTRUCTS_VERSION: string | undefined;
+/**
+ * Pure core of the emitter: derive the `engineCompat` block from a given
+ * version string (or undefined). Both the absent/empty guard and the
+ * `${major}.0.0` non-integer-major derivation live here — the single source of
+ * the derivation, delegated to by both `MINIMUM_ENGINE_VERSION` and
+ * `buildEngineCompat` — so the fail-safe and malformed-version paths are
+ * unit-testable directly, without mocking module-load state. Returns undefined
+ * when the version is absent, empty, or has no valid integer major (fail-safe:
+ * the caller stamps no block).
+ */
+export declare function buildEngineCompatFrom(version: string | undefined): EngineCompat | undefined;
+/**
+ * The compatible deploy-engine floor for assemblies this constructs version
+ * synthesises: `${major}.0.0`, derived from `CONSTRUCTS_VERSION`. `undefined`
+ * when the version is unresolved or has a non-integer major (in which case
+ * `buildEngineCompat` stamps no block — fail-safe).
+ */
+export declare const MINIMUM_ENGINE_VERSION: string | undefined;
+/**
+ * Build the `engineCompat` block to stamp into the manifest, or `undefined`
+ * when the constructs' own version cannot be resolved (fail-safe: the caller
+ * stamps no block and the deploy degrades to a constraint-free proceed).
+ *
+ * Phase 1 emits only the two required fields. The verdict classification of the
+ * emitted floor is proven in `@fjall/deploy-core`'s
+ * `orchestration/application/__tests__/engineCompat.test.ts` (a `4.0.0` floor
+ * refuses a 3.x engine, proceeds for 4.x/5.x); this module's tests prove the
+ * emitted shape matches that floor and reads back through the gate's reader.
+ */
+export declare function buildEngineCompat(): EngineCompat | undefined;

package/dist/lib/utils/engineCompat.js

@@ -0,0 +1,118 @@
+/**
+ * Synth-time engine-compatibility stamp (the contract's self-honest emitter).
+ *
+ * The constructs package is the one place that knows which deploy engine can
+ * safely deploy the assembly THIS version of the constructs produced, so it is
+ * the correct emitter of the engine ↔ assembly version contract. At synth,
+ * `writeManifest` stamps the `engineCompat` block this module builds into
+ * `cdk.out/fjall-manifest.json`; the deploy engine (`@fjall/deploy-core`) reads
+ * it back at deploy-start (`readEngineCompatEnvelope` + `evaluateEngineCompat`)
+ * and refuses an incompatible pairing before any build / push / CloudFormation
+ * mutation. Both the CLI and the webapp worker inherit that one chokepoint.
+ *
+ * `synthesisedBy` is the constructs' OWN package version — audit/diagnostics
+ * only, never a gate input. It is resolved at module load by the same upward
+ * `package.json` walk `@fjall/deploy-core`'s `DEPLOY_CORE_VERSION` uses: the
+ * source layout (`lib/utils/engineCompat.ts`) and the compiled layout
+ * (`dist/lib/utils/engineCompat.js`) sit at different depths from the package
+ * root, so a fixed relative path would resolve the wrong file in one of them;
+ * matching on `name` finds the right `package.json` from both, and skips any
+ * unrelated `package.json` higher up (e.g. a consuming app's).
+ *
+ * `minimumEngineVersion` is the PRIMARY refuse gate. Under Lerna FIXED lockstep
+ * every `@fjall/*` package shares one version, so the compatible engine floor
+ * is this constructs major with a zeroed minor/patch (`${major}.0.0`) — DERIVED,
+ * never hardcoded, so it advances to `5.0.0` on the next major with no
+ * hand-edit. A same-major-or-newer engine proceeds; an older-major engine
+ * hard-refuses.
+ *
+ * The optional `maximumEngineMajor` / `minimumAwsCdkCli` bounds are deliberately
+ * NOT emitted in Phase 1 — they are ADR open question Q5 (engine-ahead cap) and
+ * the Phase-2 FM1 aws-cdk floor graft respectively, both unresolved and
+ * deferred. This emitter stamps only the two required fields.
+ *
+ * Fail-safe: if the constructs' own version cannot be resolved (a broken
+ * package layout), `buildEngineCompat` returns undefined and the caller stamps
+ * NO block — degrading to the constraint-free "proceed" behaviour that predates
+ * this contract rather than breaking synth. A resolution failure is logged, not
+ * silently swallowed.
+ */
+import { fileURLToPath } from "url";
+import { dirname, join, parse } from "path";
+import { existsSync, readFileSync } from "fs";
+import { getErrorMessage, maskSensitiveOutput } from "@fjall/util";
+import { FjallLogger } from "./validationLogger.js";
+const PACKAGE_NAME = "@fjall/components-infrastructure";
+function resolveConstructsVersion() {
+    try {
+        let dir = dirname(fileURLToPath(import.meta.url));
+        const { root } = parse(dir);
+        for (;;) {
+            const candidate = join(dir, "package.json");
+            if (existsSync(candidate)) {
+                const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+                if (pkg.name === PACKAGE_NAME &&
+                    typeof pkg.version === "string" &&
+                    pkg.version.length > 0) {
+                    return pkg.version;
+                }
+            }
+            if (dir === root)
+                return undefined;
+            dir = dirname(dir);
+        }
+    }
+    catch (error) {
+        FjallLogger.warn(`Could not resolve ${PACKAGE_NAME} version for engineCompat: ` +
+            maskSensitiveOutput(getErrorMessage(error)));
+        return undefined;
+    }
+}
+/**
+ * The constructs' own package version — the assembly's `synthesisedBy`.
+ * `undefined` only when the package layout is broken enough that the upward
+ * walk finds no matching `package.json`.
+ */
+export const CONSTRUCTS_VERSION = resolveConstructsVersion();
+/**
+ * Pure core of the emitter: derive the `engineCompat` block from a given
+ * version string (or undefined). Both the absent/empty guard and the
+ * `${major}.0.0` non-integer-major derivation live here — the single source of
+ * the derivation, delegated to by both `MINIMUM_ENGINE_VERSION` and
+ * `buildEngineCompat` — so the fail-safe and malformed-version paths are
+ * unit-testable directly, without mocking module-load state. Returns undefined
+ * when the version is absent, empty, or has no valid integer major (fail-safe:
+ * the caller stamps no block).
+ */
+export function buildEngineCompatFrom(version) {
+    if (version === undefined || version.length === 0)
+        return undefined;
+    const major = Number(version.split(".")[0]);
+    if (!Number.isInteger(major) || major < 0)
+        return undefined;
+    return {
+        synthesisedBy: version,
+        minimumEngineVersion: `${major}.0.0`
+    };
+}
+/**
+ * The compatible deploy-engine floor for assemblies this constructs version
+ * synthesises: `${major}.0.0`, derived from `CONSTRUCTS_VERSION`. `undefined`
+ * when the version is unresolved or has a non-integer major (in which case
+ * `buildEngineCompat` stamps no block — fail-safe).
+ */
+export const MINIMUM_ENGINE_VERSION = buildEngineCompatFrom(CONSTRUCTS_VERSION)?.minimumEngineVersion;
+/**
+ * Build the `engineCompat` block to stamp into the manifest, or `undefined`
+ * when the constructs' own version cannot be resolved (fail-safe: the caller
+ * stamps no block and the deploy degrades to a constraint-free proceed).
+ *
+ * Phase 1 emits only the two required fields. The verdict classification of the
+ * emitted floor is proven in `@fjall/deploy-core`'s
+ * `orchestration/application/__tests__/engineCompat.test.ts` (a `4.0.0` floor
+ * refuses a 3.x engine, proceeds for 4.x/5.x); this module's tests prove the
+ * emitted shape matches that floor and reads back through the gate's reader.
+ */
+export function buildEngineCompat() {
+    return buildEngineCompatFrom(CONSTRUCTS_VERSION);
+}

package/dist/lib/utils/manifestWriter.js

@@ -19,6 +19,7 @@ import { createHash } from "crypto";
 import { buildConstructMap, constructMapToRecord, ACCOUNT_CONSTRUCT_GROUPS } from "@fjall/util/constructMap";
 import { getErrorMessage, maskSensitiveOutput } from "@fjall/util";
 import { FJALL_MANIFEST_FILENAME, MANIFEST_SCHEMA_VERSION, FjallManifestSchema } from "@fjall/util/manifest/schemas";
+import { buildEngineCompat } from "./engineCompat.js";
 import { FjallLogger } from "./validationLogger.js";
 /**
  * Collected manifest data during synthesis.
@@ -170,6 +171,12 @@ export function writeManifest(assembly, collector) {
     const stacks = computeStackHashes(cdkOutPath);
     // Build resource map from CDK manifest metadata
     const constructMap = buildConstructMap(cdkOutPath, collector.getConstructGroups());
+    const engineCompat = buildEngineCompat();
+    if (engineCompat === undefined) {
+        FjallLogger.warn("Could not determine constructs version — manifest stamped with no " +
+            "engineCompat block; the deploy engine will proceed without a " +
+            "version-compatibility gate.");
+    }
     const manifest = {
         version: MANIFEST_SCHEMA_VERSION,
         generatedAt: new Date().toISOString(),
@@ -177,6 +184,7 @@ export function writeManifest(assembly, collector) {
         services: collector.getServices(),
         lambdas: collector.getLambdas(),
         stacks,
+        ...(engineCompat !== undefined ? { engineCompat } : {}),
         ...(constructMap.size > 0
             ? { resourceMap: constructMapToRecord(constructMap) }
             : {})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
@@ -67,8 +67,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1038.0",
-    "@fjall/generator": "^4.1.0",
-    "@fjall/util": "^4.1.0",
+    "@fjall/generator": "^4.3.0",
+    "@fjall/util": "^4.3.0",
     "constructs": "^10.6.0"
   },
   "overrides": {
@@ -82,5 +82,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "gitHead": "09dee795753839b82aedbb7d0cef1c5ef283df55"
+  "gitHead": "8a3ae096f9d15c47dc8c277c9bddfa40e4168c19"
 }