@fjall/components-infrastructure 0.96.0 → 0.99.1

package/dist/lib/patterns/aws/interfaces/database.d.ts

@@ -15,19 +15,44 @@
  */
 import { type ITable } from "aws-cdk-lib/aws-dynamodb";
 import { type IConnectable } from "aws-cdk-lib/aws-ec2";
-import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
+import { type TaskDefinition } from "aws-cdk-lib/aws-ecs";
+import { type IGrantable, type Grant, type PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { type IBucket } from "aws-cdk-lib/aws-s3";
 import { type Construct } from "constructs";
 import { type Secret } from "../../../resources/aws/secrets/index.js";
+import { type SnapshotTarget } from "../../../utils/databaseTypes.js";
+import { type IMigrationContributor } from "./migrationContributor.js";
+export { type SnapshotTarget } from "../../../utils/databaseTypes.js";
+export { MIGRATION_SNAPSHOT_NAME_PREFIX, EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV } from "@fjall/util";
+/**
+ * Declarative migration configuration on a relational database. Drives:
+ *  - the schema-version resolver at synth (filesystem scan of `dir`)
+ *  - the env auto-injection through every connected service's containers
+ *
+ * `tool: "prisma"` uses the built-in `^\d{14}_/` directory-name resolver.
+ * `tool: "custom"` accepts a user-supplied resolver — pure function from
+ * directory path to version string. Drizzle / Flyway / Rails users wire
+ * their own resolver without waiting for first-class support.
+ */
+export type MigrationsConfig = {
+    readonly tool: "prisma";
+    readonly dir: string;
+} | {
+    readonly tool: "custom";
+    readonly dir: string;
+    readonly versionResolver: (dir: string) => string;
+};
 /**
  * Database type discriminator.
  * Relational types share the IRelationalDatabase interface.
  * DynamoDB has its own IDynamoDBDatabase interface.
  */
-export type DatabaseType = "Aurora" | "Instance" | "GlobalAurora" | "DynamoDB";
+export type DatabaseType = "Aurora" | "Instance" | "GlobalAurora" | "DynamoDB" | "ClickHouse";
 /**
  * Relational database type discriminator.
  */
-export type RelationalDatabaseType = "Aurora" | "Instance" | "GlobalAurora";
+export declare const RELATIONAL_DATABASE_TYPES: readonly ["Aurora", "Instance", "GlobalAurora"];
+export type RelationalDatabaseType = (typeof RELATIONAL_DATABASE_TYPES)[number];
 /**
  * Base database interface.
  * All database types implement this interface.
@@ -39,19 +64,74 @@ export interface IDatabase {
     readonly node: Construct["node"];
 }
 /**
- * Relational database interface (Aurora, RDS Instance, GlobalAurora).
- * Provides access to connection details, credentials, and security group connections.
+ * Shared base for all relational databases (Aurora, RDS Instance, GlobalAurora).
+ * Carries everything that does not depend on the variant — connection details,
+ * credentials, snapshot target, security group connections.
  */
-export interface IRelationalDatabase extends IDatabase, IConnectable {
+export interface IRelationalDatabaseBase extends IDatabase, IConnectable, IMigrationContributor {
     readonly databaseType: RelationalDatabaseType;
     /** Get the database host endpoint. */
     getHostEndpoint(): string;
     /** Get the database port. */
     getHostPort(): string;
+    /**
+     * Database connection string WITHOUT credentials.
+     * Returns `<scheme>://<host>:<port>/<dbname>` where scheme is `postgresql` or
+     * `mysql` depending on engine family.
+     *
+     * Callers compose the final URL at runtime by injecting credentials from
+     * `getCredentials().getImport(...)`. Credentials are deliberately excluded
+     * from the connection string because Secrets Manager `SecretValue` references
+     * cannot be safely interpolated at synth time — leaking them to the URL
+     * would bake plaintext into the CloudFormation template.
+     *
+     * @example
+     *   // Synth time (CDK):
+     *   environment: { DATABASE_URL_BASE: database.getConnectionString() }
+     *   secretsImport: {
+     *     DATABASE_USER: database.getCredentials().getImport("username"),
+     *     DATABASE_PASSWORD: database.getCredentials().getImport("password"),
+     *   }
+     *   // Runtime (app):
+     *   const u = new URL(process.env.DATABASE_URL_BASE);
+     *   u.username = process.env.DATABASE_USER;
+     *   u.password = process.env.DATABASE_PASSWORD;
+     *   const finalUrl = u.toString();
+     */
+    getConnectionString(): string;
     /** Get the database name. */
     getDatabaseName(): string;
     /** Get the database credentials secret (Fjall Secret wrapper with getImport() support). */
     getCredentials(): Secret;
+    /**
+     * Discriminated snapshot target. Instance variants return
+     * `{ kind: "instance", arn }`; cluster variants return
+     * `{ kind: "cluster", arn }`. Consumers branch on `kind` to choose between
+     * `rds:CreateDBSnapshot` and `rds:CreateDBClusterSnapshot`.
+     */
+    getSnapshotTarget(): SnapshotTarget;
+    /**
+     * Returns the IAM PolicyStatement granting the migration runner the rights
+     * needed to take and tag a pre-migration snapshot of this database. Action
+     * triple and resource ARN segment derive from `this.getSnapshotTarget().kind`.
+     * Snapshot name glob is bound to `MIGRATION_SNAPSHOT_NAME_PREFIX`.
+     */
+    getMigrationSnapshotPolicy(): PolicyStatement;
+    /**
+     * Returns the migration configuration declared on this database, or
+     * `undefined` if the user did not declare one. When set, every container
+     * of every service in this database's `connections:` graph receives an
+     * `EXPECTED_SCHEMA_VERSION` env entry (unless service-level
+     * `schemaGate: false`).
+     */
+    getMigrationsConfig(): MigrationsConfig | undefined;
+    /**
+     * Resolves `migrations.dir` via the tool's resolver at synth time. Returns
+     * `undefined` when no `migrations:` was declared. Throws when declared
+     * but the directory is empty / unreadable / contains no matching entries
+     * — fail loud, never silent.
+     */
+    getExpectedSchemaVersion(): string | undefined;
     /**
      * Grant connect permissions to a grantee.
      * This adds the grantee to the database security group.
@@ -59,11 +139,39 @@ export interface IRelationalDatabase extends IDatabase, IConnectable {
      */
     grantConnect(grantee: IConnectable): void;
 }
+/**
+ * Single-instance RDS variant. Exposes the instance identifier directly and
+ * narrows `getSnapshotTarget()` to the `"instance"` arm of the discriminated union.
+ */
+export interface IRelationalInstanceDatabase extends IRelationalDatabaseBase {
+    /** RDS DB instance identifier for `rds:CreateDBSnapshot`. */
+    getInstanceIdentifier(): string;
+    getSnapshotTarget(): Extract<SnapshotTarget, {
+        kind: "instance";
+    }>;
+}
+/**
+ * Aurora cluster variant (regional or global). Exposes the cluster identifier
+ * directly and narrows `getSnapshotTarget()` to the `"cluster"` arm.
+ */
+export interface IRelationalClusterDatabase extends IRelationalDatabaseBase {
+    /** RDS DB cluster identifier for `rds:CreateDBClusterSnapshot`. */
+    getClusterIdentifier(): string;
+    getSnapshotTarget(): Extract<SnapshotTarget, {
+        kind: "cluster";
+    }>;
+}
+/**
+ * Relational database interface — discriminated union of the variant
+ * interfaces. Consumers either narrow on `databaseType` (or via `kind` after
+ * `getSnapshotTarget()`), or accept the union and branch exhaustively.
+ */
+export type IRelationalDatabase = IRelationalInstanceDatabase | IRelationalClusterDatabase;
 /**
  * DynamoDB database interface.
  * Provides access to table-specific methods and IAM grants.
  */
-export interface IDynamoDBDatabase extends IDatabase {
+export interface IDynamoDBDatabase extends IDatabase, IMigrationContributor {
     readonly databaseType: "DynamoDB";
     /** Get the table name. */
     getTableName(): string;
@@ -99,11 +207,78 @@ export interface IDynamoDBDatabase extends IDatabase {
      */
     grantStreamRead(grantee: IGrantable): Grant;
 }
+/**
+ * ClickHouse analytics database interface.
+ *
+ * Per the 2026-05-14 Phase 4b `users:` prop iteration, ClickHouse exposes
+ * its workload users via the `users:` construct prop. Consumers look them
+ * up by name via `getUser(name)` — there are no typed accessors for
+ * specific roles.
+ *
+ * Cold-tier bucket access is conditional: `getColdTierBucket()` returns
+ * `undefined` when the user disabled the cold tier via `coldTier: false`
+ * (per D12 + D19).
+ */
+export interface IClickHouseDatabase extends IDatabase, IConnectable, IMigrationContributor {
+    readonly databaseType: "ClickHouse";
+    /**
+     * Returns the Fjall `Secret` wrapper for the named user. Throws with a
+     * `Known users:` list if the name is not present in the `users:` prop.
+     */
+    getUser(name: string): Secret;
+    /**
+     * Returns the Fjall `Secret` wrapper for the named user, or `undefined`
+     * when the user is not declared. Use for optional secret contributions
+     * (e.g. `SCHEMA_ADMIN_PASSWORD` only when a `schema_admin` user exists).
+     */
+    tryGetUser(name: string): Secret | undefined;
+    /**
+     * Wires a task definition to connect to ClickHouse as `opts.user` (if
+     * supplied). Adds `CLICKHOUSE_URL` / `CLICKHOUSE_DATABASE` env vars to the
+     * task's default container; when `opts.user` is set, also adds
+     * `CLICKHOUSE_USER` (plain env) and `CLICKHOUSE_PASSWORD` (Secrets
+     * Manager-backed). Callers separately call `grantConnect(service)` on the
+     * resulting ECS service for the network grant.
+     */
+    connectFromTask(task: TaskDefinition, opts?: {
+        user?: string;
+    }): void;
+    /** HTTP port (typically 8123). */
+    getHttpPort(): number;
+    /** Native TCP port (typically 9000). */
+    getNativePort(): number;
+    /**
+     * HTTP URL for clickhouse-client / chproxy (`http://<host>:<httpPort>`).
+     * No credentials in the URL — ClickHouse HTTP uses Basic Auth headers or
+     * `X-ClickHouse-User`/`X-ClickHouse-Key` headers. Compose creds at runtime
+     * via `getUser(name).getImport(...)`.
+     */
+    getHttpUrl(): string;
+    /**
+     * Native TCP URL (`tcp://<host>:<nativePort>`).
+     * No credentials in the URL — the native protocol handshake carries them.
+     */
+    getNativeUrl(): string;
+    /** Get the database host endpoint (Cloud Map FQDN). */
+    getHostEndpoint(): string;
+    /** Get the database name. */
+    getDatabaseName(): string;
+    /** Get the backup bucket. */
+    getBackupBucket(): IBucket;
+    /** Get the cold-tier bucket, or `undefined` when cold-tier storage is disabled. */
+    getColdTierBucket(): IBucket | undefined;
+    /**
+     * Grant connect permissions to a grantee.
+     * Adds the grantee to the database security group on both ports.
+     * @param grantee The principal to grant connect permissions to
+     */
+    grantConnect(grantee: IConnectable): void;
+}
 /**
  * Union type representing any database interface.
  * Use with type guards for generic handling.
  */
-export type AnyDatabase = IRelationalDatabase | IDynamoDBDatabase;
+export type AnyDatabase = IRelationalDatabase | IDynamoDBDatabase | IClickHouseDatabase;
 /**
  * Type guard to check if a database is relational (Aurora, Instance, GlobalAurora).
  */
@@ -112,6 +287,10 @@ export declare function isRelationalDatabase(database: IDatabase): database is I
  * Type guard to check if a database is DynamoDB.
  */
 export declare function isDynamoDBDatabase(database: IDatabase): database is IDynamoDBDatabase;
+/**
+ * Type guard to check if a database is ClickHouse.
+ */
+export declare function isClickHouseDatabase(database: IDatabase): database is IClickHouseDatabase;
 /**
  * Type guard to check if a database is Aurora.
  */

package/dist/lib/patterns/aws/interfaces/database.js

@@ -13,13 +13,21 @@
  * dynamo.getTableName(); // ✓ Available on IDynamoDBDatabase
  * dynamo.getHostEndpoint(); // ✗ Compile error - not on IDynamoDBDatabase
  */
+export { MIGRATION_SNAPSHOT_NAME_PREFIX, EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV } from "@fjall/util";
+/**
+ * Relational database type discriminator.
+ */
+export const RELATIONAL_DATABASE_TYPES = [
+    "Aurora",
+    "Instance",
+    "GlobalAurora"
+];
+const RELATIONAL_DATABASE_TYPE_SET = new Set(RELATIONAL_DATABASE_TYPES);
 /**
  * Type guard to check if a database is relational (Aurora, Instance, GlobalAurora).
  */
 export function isRelationalDatabase(database) {
-    return (database.databaseType === "Aurora" ||
-        database.databaseType === "Instance" ||
-        database.databaseType === "GlobalAurora");
+    return RELATIONAL_DATABASE_TYPE_SET.has(database.databaseType);
 }
 /**
  * Type guard to check if a database is DynamoDB.
@@ -27,6 +35,12 @@ export function isRelationalDatabase(database) {
 export function isDynamoDBDatabase(database) {
     return database.databaseType === "DynamoDB";
 }
+/**
+ * Type guard to check if a database is ClickHouse.
+ */
+export function isClickHouseDatabase(database) {
+    return database.databaseType === "ClickHouse";
+}
 /**
  * Type guard to check if a database is Aurora.
  */

package/dist/lib/patterns/aws/interfaces/index.d.ts

@@ -5,7 +5,8 @@
  * factory pattern implementations.
  */
 export { type ComputeType, type ICompute, type IEcsCompute, type ILambdaCompute, type IEc2Compute, type AnyCompute, isCompute, isEcsCompute, isLambdaCompute, isEc2Compute } from "./compute.js";
-export { type DatabaseType, type RelationalDatabaseType, type IDatabase, type IRelationalDatabase, type IDynamoDBDatabase, type AnyDatabase, isDatabase, isRelationalDatabase, isDynamoDBDatabase, isAuroraDatabase, isInstanceDatabase, isGlobalAuroraDatabase } from "./database.js";
+export { type DatabaseType, type RelationalDatabaseType, type IDatabase, type IRelationalDatabase, type IDynamoDBDatabase, type AnyDatabase, type MigrationsConfig, isDatabase, isRelationalDatabase, isDynamoDBDatabase, isAuroraDatabase, isInstanceDatabase, isGlobalAuroraDatabase, MIGRATION_SNAPSHOT_NAME_PREFIX, EXPECTED_SCHEMA_VERSION_ENV } from "./database.js";
+export { type MigrationContributions, type IMigrationContributor, isMigrationContributor } from "./migrationContributor.js";
 export { type MessagingType, type IMessaging, type IQueueMessaging, type ITopicMessaging, type IEventBusMessaging, type AnyMessaging, isMessaging, isQueueMessaging, isTopicMessaging, isEventBusMessaging } from "./messaging.js";
 export { type IStorage, isStorage } from "./storage.js";
 export { type CdnType, type ICdn, type AnyCdn, isCdn } from "./cdn.js";

package/dist/lib/patterns/aws/interfaces/index.js

@@ -7,7 +7,9 @@
 // Compute interfaces
 export { isCompute, isEcsCompute, isLambdaCompute, isEc2Compute } from "./compute.js";
 // Database interfaces
-export { isDatabase, isRelationalDatabase, isDynamoDBDatabase, isAuroraDatabase, isInstanceDatabase, isGlobalAuroraDatabase } from "./database.js";
+export { isDatabase, isRelationalDatabase, isDynamoDBDatabase, isAuroraDatabase, isInstanceDatabase, isGlobalAuroraDatabase, MIGRATION_SNAPSHOT_NAME_PREFIX, EXPECTED_SCHEMA_VERSION_ENV } from "./database.js";
+// Migration contributor (per-resource contribution shape)
+export { isMigrationContributor } from "./migrationContributor.js";
 // Messaging interfaces
 export { isMessaging, isQueueMessaging, isTopicMessaging, isEventBusMessaging } from "./messaging.js";
 // Storage interfaces

package/dist/lib/patterns/aws/interfaces/messaging.d.ts

@@ -25,6 +25,7 @@ import { type ITopic } from "aws-cdk-lib/aws-sns";
 import { type IEventBus } from "aws-cdk-lib/aws-events";
 import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
 import { type Construct } from "constructs";
+import type { Subscription, SubscriptionProps } from "../../../resources/aws/messaging/subscription.js";
 export type { IQueue, ITopic, IEventBus };
 /**
  * Messaging type discriminator.
@@ -123,6 +124,12 @@ export interface IEventBusMessaging extends IMessaging {
      * @param grantee The principal to grant put events permissions to
      */
     grantPutEventsTo(grantee: IGrantable): Grant;
+    /**
+     * Add a pub/sub subscription scoped to this bus. The returned `Subscription`
+     * handle exposes `getRule()` / `getRuleArn()` / `deadLetterQueue?` per the
+     * shared four-member EventBridge surface.
+     */
+    subscribe(id: string, props: SubscriptionProps): Subscription;
 }
 /**
  * Union type representing any messaging interface.

package/dist/lib/patterns/aws/interfaces/migrationContributor.d.ts

@@ -0,0 +1,47 @@
+import { type IPeer, type Port } from "aws-cdk-lib/aws-ec2";
+import { type PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { type SecretImport } from "../../../resources/aws/secrets/index.js";
+/**
+ * What a resource contributes to a migration task that connects to it.
+ *
+ * The framework merges contributions from every `IMigrationContributor` in the
+ * parent service's `connections:` array and wires the result into the separate
+ * migration task definition. Author-explicit values in the service's
+ * `migrations:` block win on collision (env / secrets) with a synth warning;
+ * `taskRolePolicies` and `egress` are additively merged.
+ *
+ * Consumed by `synthesiseMigrationTaskDef` at
+ * `lib/patterns/aws/computeEcs.ts § synthesiseMigrationTaskDef` via the
+ * module-private `collectMigrationContributions` helper.
+ */
+export interface MigrationContributions {
+    /** Env vars to inject into the migration task's main container. */
+    readonly environment?: Record<string, string>;
+    /** Secrets-Manager imports to inject. */
+    readonly secretsImport?: Record<string, SecretImport>;
+    /** IAM policy statements to attach to the migration task role. */
+    readonly taskRolePolicies?: readonly PolicyStatement[];
+    /**
+     * Egress rules to wire from the migration task to this resource. The
+     * framework constructs the migration SG (when any contributor has egress)
+     * and calls `addEgressRule(peer, port, description)` for each entry.
+     */
+    readonly egress?: ReadonlyArray<{
+        readonly peer: IPeer;
+        readonly port: Port;
+        readonly description: string;
+    }>;
+}
+/**
+ * Opt-in structural interface. Resources implement this to declare what they
+ * contribute when a migration task connects to them via the parent service's
+ * `connections:` array. Return `undefined` to contribute nothing.
+ */
+export interface IMigrationContributor {
+    getMigrationContributions(): MigrationContributions | undefined;
+}
+/**
+ * Structural type guard. Used by `collectMigrationContributions` to dispatch
+ * over heterogeneous `connections:` entries.
+ */
+export declare function isMigrationContributor(x: unknown): x is IMigrationContributor;

package/dist/lib/patterns/aws/interfaces/migrationContributor.js

@@ -0,0 +1,9 @@
+/**
+ * Structural type guard. Used by `collectMigrationContributions` to dispatch
+ * over heterogeneous `connections:` entries.
+ */
+export function isMigrationContributor(x) {
+    return (x !== null &&
+        typeof x === "object" &&
+        typeof x.getMigrationContributions === "function");
+}

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

@@ -1,9 +1,12 @@
 import { type Construct } from "constructs";
 import { type IGrantable, type Grant } from "aws-cdk-lib/aws-iam";
+import { type IEventBus } from "aws-cdk-lib/aws-events";
 import type App from "../../app.js";
 import { SQSQueue } from "../../resources/aws/messaging/sqs.js";
-import { SNSTopic } from "../../resources/aws/messaging/sns.js";
+import { SNSTopic, type SNSTopicProps } from "../../resources/aws/messaging/sns.js";
 import { EventBridgeBus } from "../../resources/aws/messaging/eventbridge.js";
+import { type RemovalPolicyString } from "../../resources/aws/messaging/utils.js";
+import { Subscription, type SubscriptionProps } from "../../resources/aws/messaging/subscription.js";
 import { type IQueueMessaging, type ITopicMessaging, type IEventBusMessaging, type AnyMessaging } from "./interfaces/messaging.js";
 import { type IQueueConnector } from "./interfaces/connector.js";
 /**
@@ -27,19 +30,16 @@ export interface IQueueProps {
     contentBasedDeduplication?: boolean;
     fifoThroughputLimit?: "perQueue" | "perMessageGroupId";
     deduplicationScope?: "queue" | "messageGroup";
-    removalPolicy?: "DESTROY" | "RETAIN";
+    removalPolicy?: RemovalPolicyString;
 }
 /**
- * Topic messaging props with type discriminator.
+ * Topic messaging props with type discriminator. Extends SNSTopicProps so the
+ * pattern surface stays in lockstep with the resource — adding a field to
+ * SNSTopicProps automatically reaches the pattern entrypoint.
  */
-export interface ITopicProps {
+export interface ITopicProps extends SNSTopicProps {
     /** Type discriminator for messaging type. */
     type: "topic";
-    topicName?: string;
-    displayName?: string;
-    fifo?: boolean;
-    contentBasedDeduplication?: boolean;
-    removalPolicy?: "DESTROY" | "RETAIN";
 }
 /**
  * EventBus messaging props with type discriminator.
@@ -48,7 +48,24 @@ export interface IEventBusProps {
     /** Type discriminator for messaging type. */
     type: "eventBus";
     eventBusName?: string;
-    removalPolicy?: "DESTROY" | "RETAIN";
+    appName?: string;
+    description?: string;
+    removalPolicy?: RemovalPolicyString;
+    /**
+     * Internal: forwarded to `EventBridgeBusProps.importedBus` so
+     * `EventBusMessaging.fromEventBusArn(...)` skips creating a fresh
+     * `AWS::Events::EventBus`. Per D19 the wrapper holds the imported handle
+     * and bus-level mutations are no-ops.
+     */
+    importedBus?: IEventBus;
+    /**
+     * Internal: marks the wrapper as targeting the AWS-managed account+region
+     * default bus rather than a custom Fjall app bus. Set by
+     * `EventBusMessaging.fromAwsServiceBus(...)`. Disables the `aws.*`
+     * source-pattern guard on `subscribe(...)` since AWS service events fire
+     * only on the default bus.
+     */
+    awsServiceBus?: boolean;
 }
 /**
  * Union type for all messaging props.
@@ -114,6 +131,7 @@ export declare class TopicMessaging extends SNSTopic implements ITopicMessaging
  * Provides grant methods and Fjall patterns for event-driven messaging.
  */
 export declare class EventBusMessaging extends EventBridgeBus implements IEventBusMessaging {
+    #private;
     /** Type discriminator for runtime type narrowing. */
     readonly messagingType: "eventBus";
     constructor(scope: Construct, id: string, props: IEventBusProps);
@@ -122,6 +140,43 @@ export declare class EventBusMessaging extends EventBridgeBus implements IEventB
      * Implements IEventBusMessaging.grantPutEventsTo.
      */
     grantPutEventsTo(grantee: IGrantable): Grant;
+    /**
+     * Add a pub/sub subscription scoped to this bus. Threads the bus's
+     * `IEventBus` and the captured `appName` into the Subscription so the
+     * synthesised rule attaches to this bus (not the default AWS bus) and the
+     * default description picks up the bus's app context.
+     *
+     * Refuses `aws.*` source patterns when the wrapper is an app bus rather
+     * than the AWS-managed default bus. AWS service events fire only on the
+     * account+region default bus; subscribing them on a custom app bus
+     * synthesises and deploys cleanly but never invokes the target. Use
+     * `EventBusMessaging.fromAwsServiceBus(...)` to import the default bus
+     * for AWS service event traffic.
+     */
+    subscribe(id: string, props: SubscriptionProps): Subscription;
+    /**
+     * Wrap a bus imported from another account/region by ARN per D19. The
+     * returned handle supports `subscribe(...)` identically to created buses;
+     * rules are owned by the importing stack and attach to the imported bus's
+     * ARN. The base wrapper short-circuits resource creation when `importedBus`
+     * is set, so no `AWS::Events::EventBus` is synthesised and bus-level
+     * mutations (description, removalPolicy, CfnOutputs) are skipped.
+     */
+    static fromEventBusArn(scope: Construct, id: string, arn: string): EventBusMessaging;
+    /**
+     * Wrap the AWS-managed account+region `default` event bus. This is the
+     * bus that receives `aws.*` service events emitted via CloudTrail
+     * (`aws.ecr` `CreateRepository`, `aws.ec2` state-change, etc.); custom
+     * Fjall app buses do not receive this traffic. The returned wrapper has
+     * the AWS-service brand set, so `subscribe(...)` accepts `aws.*` source
+     * patterns; subscribing app-source patterns is still allowed but
+     * unusual (the canonical app-source path is `app.getEventBus()`).
+     *
+     * @param region AWS region holding the default bus (typically the stack
+     * region — the default bus is per-account-per-region).
+     * @param account AWS account id holding the default bus.
+     */
+    static fromAwsServiceBus(scope: Construct, id: string, region: string, account: string): EventBusMessaging;
 }
 /**
  * Factory for creating messaging resources.
@@ -179,5 +234,6 @@ export declare class MessagingFactory {
 export type { SQSQueueProps } from "../../resources/aws/messaging/sqs.js";
 export type { SNSTopicProps } from "../../resources/aws/messaging/sns.js";
 export type { EventBridgeBusProps } from "../../resources/aws/messaging/eventbridge.js";
+export { EventField, RuleTargetInput, type EventPattern } from "aws-cdk-lib/aws-events";
 export type { IQueueMessaging, ITopicMessaging, IEventBusMessaging, AnyMessaging, IQueue, ITopic, IEventBus } from "./interfaces/messaging.js";
 export { isQueueMessaging, isTopicMessaging, isEventBusMessaging } from "./interfaces/messaging.js";