@openhi/constructs 0.0.104 → 0.0.106

package/lib/index.d.mts

@@ -9,19 +9,25 @@ import { Key, KeyProps, IKey } from 'aws-cdk-lib/aws-kms';
 import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
 import { D as DynamoDbStreamKinesisRecord } from './dynamodb-stream-record-CJtV6a1t.mjs';
 import * as events from 'aws-cdk-lib/aws-events';
-import { EventBus, EventBusProps, IEventBus } from 'aws-cdk-lib/aws-events';
+import { EventBus, EventBusProps, Rule, IEventBus } from 'aws-cdk-lib/aws-events';
 import * as kinesis from 'aws-cdk-lib/aws-kinesis';
 import * as kinesisfirehose from 'aws-cdk-lib/aws-kinesisfirehose';
 import * as s3 from 'aws-cdk-lib/aws-s3';
 import { IBucket, BucketProps } from 'aws-cdk-lib/aws-s3';
 import { Table, TableProps, ITable } from 'aws-cdk-lib/aws-dynamodb';
+import { Function, IFunction } from 'aws-cdk-lib/aws-lambda';
 import * as ec2 from 'aws-cdk-lib/aws-ec2';
 import * as rds from 'aws-cdk-lib/aws-rds';
 import { HostedZone, HostedZoneProps, IHostedZone, HostedZoneAttributes } from 'aws-cdk-lib/aws-route53';
 import { StringParameterProps, StringParameter } from 'aws-cdk-lib/aws-ssm';
 import { Distribution, DistributionProps } from 'aws-cdk-lib/aws-cloudfront';
-import { IFunction } from 'aws-cdk-lib/aws-lambda';
+export { B as BRIDGED_STATUSES, a as BridgedStatus, C as CLOUDFORMATION_EVENT_SOURCE, b as CLOUDFORMATION_STACK_STATUS_CHANGE_DETAIL_TYPE, c as CONTROL_EVENT_BUS_NAME_ENV_VAR, d as CloudFormationStackStatusChangeDetail, O as OPENHI_REPO_TAG_KEY_ENV_VAR, e as OPENHI_TAG_KEY_PREFIX_ENV_VAR, P as PLATFORM_DEPLOY_BRIDGE_ACTOR_SYSTEM } from './events-BfrkMoBD.mjs';
+export { D as DEMO_PERIOD, a as DEMO_TENANT_SPECS, b as DEMO_URN_SYSTEM, c as DEV_USERS, d as DemoDevUser, e as DemoTenantSpec, f as DemoWorkspaceSpec, O as OPENHI_RESOURCE_URN_SYSTEM, P as PLACEHOLDER_TENANT_ID, g as PLACEHOLDER_WORKSPACE_ID, h as PLATFORM_SCOPE_TENANT_ID, S as SEED_DEMO_DATA_CONSUMER_NAME, i as demoBasePartitionKeys, j as demoDevUserPartitionKeys, k as demoMembershipId, l as demoMembershipPartitionKey, m as demoRoleAssignmentId, n as demoRoleAssignmentPartitionKey, o as demoRolesForUserInTenant, p as demoScenarioIdentifier, q as demoTenantPartitionKey, r as demoUserPartitionKey, s as demoWorkspacePartitionKey, t as openhiResourceIdentifier, u as rolePartitionKey } from './events-DGep6C7w.mjs';
+export { P as PROVISION_DEFAULT_WORKSPACE_DETAIL_TYPE, a as ProvisionDefaultWorkspaceRequestedDetail, U as USER_ONBOARDING_EVENT_SOURCE, b as buildProvisionDefaultWorkspaceRequestedDetail } from './events-CVA3_eEB.mjs';
+export { PlatformDeploymentCompletedV1, PlatformSystemDataSeededV1 } from '@openhi/workflows';
 import '@aws-sdk/client-dynamodb';
+import '@openhi/types';
+import 'aws-lambda';
 
 /**
  * Properties for creating an OpenHiStage instance.
@@ -237,6 +243,28 @@ declare class OpenHiApp extends App {
  * @public
  */
 type OpenHiServiceType = "auth" | "rest-api" | "data" | "global" | "graphql-api";
+/**
+ * Tag-key suffixes applied by every OpenHiService stack via Tags.of().
+ * Full keys are composed `${appName}:${suffix}` — see {@link openHiTagKey}.
+ * Consumers that filter or project these tags (e.g. the platform-deploy
+ * bridge) import these suffixes rather than redeclaring the strings.
+ *
+ * @public
+ */
+declare const OPENHI_TAG_SUFFIX_REPO_NAME = "repo-name";
+/** @public */
+declare const OPENHI_TAG_SUFFIX_BRANCH_NAME = "branch-name";
+/** @public */
+declare const OPENHI_TAG_SUFFIX_SERVICE_TYPE = "service-type";
+/** @public */
+declare const OPENHI_TAG_SUFFIX_STAGE_TYPE = "stage-type";
+/**
+ * Compose a full stack-tag key from an `appName` and a suffix from
+ * {@link OPENHI_TAG_SUFFIX_REPO_NAME} et al.
+ *
+ * @public
+ */
+declare const openHiTagKey: (appName: string, suffix: string) => string;
 /**
  * Properties for creating an {@link OpenHiService} stack.
  *
@@ -484,16 +512,14 @@ declare class PostAuthenticationLambda extends Construct {
 
 interface PostConfirmationLambdaProps {
     /**
-     * DynamoDB data store table name. Passed to the Lambda as DYNAMO_TABLE_NAME
-     * so the control-plane ElectroDB service writes to the same single-table store.
+     * Control-plane EventBridge bus name. Passed to the Lambda as
+     * CONTROL_EVENT_BUS_NAME so it can publish onboarding workflow events.
      */
-    readonly dynamoTableName: string;
+    readonly controlEventBusName: string;
 }
 /**
- * Lambda used as Cognito Post Confirmation trigger. Creates the new user's
- * default Tenant, Workspace, Memberships, and RoleAssignment, plus a User
- * record carrying the Cognito `sub` and current tenant/workspace pointers
- * (ADR 2026-03-17-01).
+ * Lambda used as Cognito Post Confirmation trigger. It publishes a control
+ * event and returns quickly; workflow Lambdas own provisioning.
  */
 declare class PostConfirmationLambda extends Construct {
     readonly lambda: NodejsFunction;
@@ -631,6 +657,108 @@ declare class DynamoDbDataStore extends Table {
     constructor(scope: Construct, id: string, props?: DynamoDbDataStoreProps);
 }
 
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/components/dynamodb/workflow-dedup-table.md
+ */
+/**
+ * Deterministic table name for the shared workflow dedup table.
+ * Mirrors `getDynamoDbDataStoreTableName` naming: `workflow-dedup-${branchHash}`.
+ */
+declare function getWorkflowDedupTableName(scope: Construct): string;
+/** Props for `WorkflowDedupTable`. */
+interface WorkflowDedupTableProps {
+    /**
+     * Optional removal policy override. Defaults to the service's default
+     * (RETAIN for prod, DESTROY otherwise).
+     */
+    readonly removalPolicy?: RemovalPolicy;
+}
+/** Options for `WorkflowDedupTable.grantConsumer`. */
+interface GrantConsumerOptions {
+    /**
+     * Override the default TTL applied by the runtime client. The 14-day
+     * default lives in `@openhi/workflows`; per-consumer overrides clamp
+     * shorter per TR-015. Stored in the consumer's environment so the
+     * `WorkflowDedupClient` factory can pick it up.
+     */
+    readonly defaultTtlSeconds?: number;
+}
+/**
+ * Shared platform-level dedup table every retryable workflow consumer
+ * dedupes against. Provisioned exactly once at the platform stack.
+ *
+ * Schema (per TR-015):
+ * - Partition key `consumerName` (S)
+ * - Sort key `sk` (S) — encodes `<eventId>#<attempt>`
+ * - TTL attribute `expiresAt` (N, Unix epoch seconds)
+ * - On-demand billing
+ *
+ * @see https://github.com/codedrifters/openhi-planning/blob/main/docs/src/content/docs/requirements/technical-requirements/TR-015-workflow-dedup-table.md
+ */
+declare class WorkflowDedupTable extends Construct {
+    /** SSM param name (short) used by `DiscoverableStringParameter` for the table name lookup. */
+    static readonly TABLE_NAME_SSM_PARAM_NAME = "workflow-dedup-table-name";
+    /** SSM param name (short) used by `DiscoverableStringParameter` for the table ARN lookup. */
+    static readonly TABLE_ARN_SSM_PARAM_NAME = "workflow-dedup-table-arn";
+    /** Cross-stack lookup for the table name. */
+    static tableNameFromLookup(scope: Construct): string;
+    /** Cross-stack lookup for the table ARN. */
+    static tableArnFromLookup(scope: Construct): string;
+    /**
+     * Cross-stack equivalent of {@link grantConsumer}. Use when the dedup
+     * table is on a different stack than the consumer Lambda — the
+     * grant resolves the table name + ARN via SSM at synth time, so the
+     * consumer stack does not pick up a CloudFormation export dependency
+     * on the global stack.
+     *
+     * Inverts the singleton-guard semantics of `grantConsumer`: there is
+     * no synth-time check that the same `consumerName` was registered
+     * twice across stacks. Consumer names are agreed by convention
+     * (see TR-015); double-registration is operator error caught at
+     * design time, not synth time.
+     */
+    static grantConsumerFromLookup(scope: Construct, fn: Function, consumerName: string, options?: GrantConsumerOptions): void;
+    /**
+     * Service-type the publishing stack runs under. The cross-stack lookups
+     * pin to this value so consumer stacks on a different service-type
+     * (e.g. `data`, `auth`) resolve the parameter at the publisher's SSM
+     * path instead of their own. Typed against `OpenHiServiceType` so a
+     * future rename of the literal triggers a compile error; not pulled
+     * from `OpenHiGlobalService.SERVICE_TYPE` because
+     * `OpenHiGlobalService` already imports `WorkflowDedupTable` — a
+     * back-import would create a circular dependency.
+     */
+    private static readonly PUBLISHER_SERVICE_TYPE;
+    /**
+     * Standalone consumer-name validator shared by the instance method
+     * and `grantConsumerFromLookup` so the two grants enforce identical
+     * invariants.
+     */
+    private static assertConsumerNameStatic;
+    /** The underlying DynamoDB table. */
+    readonly table: Table;
+    private readonly registeredConsumers;
+    constructor(scope: Construct, id: string, props?: WorkflowDedupTableProps);
+    /**
+     * Wire a Lambda consumer to this table. Injects the table-name env var
+     * so the runtime `WorkflowDedupClient` can resolve it, then attaches a
+     * per-consumer IAM grant scoped by `dynamodb:LeadingKeys` so the
+     * consumer can only read/write its own partition.
+     */
+    grantConsumer(fn: Function, consumerName: string, options?: GrantConsumerOptions): void;
+    private assertConsumerName;
+}
+/** Thrown when a second `WorkflowDedupTable` is instantiated in the same app. */
+declare class WorkflowDedupTableDuplicateError extends Error {
+    /** @param message - human-readable description of the duplicate. */
+    constructor(message: string);
+}
+/** Thrown when a consumerName violates the TR-015 invariants. */
+declare class WorkflowDedupConsumerNameInvalidError extends Error {
+    /** @param message - human-readable description of the invariant violation. */
+    constructor(message: string);
+}
+
 /**
  * @see sites/www-docs/content/packages/@openhi/constructs/components/event-bridge/data-event-bus.md
  */
@@ -661,6 +789,21 @@ declare class OpsEventBus extends EventBus {
     constructor(scope: Construct, props?: EventBusProps);
 }
 
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/components/event-bridge/control-event-bus.md
+ */
+declare class ControlEventBus extends EventBus {
+    /*****************************************************************************
+     *
+     * Return a name for this EventBus based on the stack environment hash. This
+     * name is common across all stacks since it's using the environment hash in
+     * its name.
+     *
+     ****************************************************************************/
+    static getEventBusName(scope: Construct): string;
+    constructor(scope: Construct, props?: EventBusProps);
+}
+
 /**
  * SSM parameter names that publish the Postgres replica's coordinates so other
  * stacks (notably the REST API stack) can discover them without a direct CDK
@@ -905,6 +1048,47 @@ declare class StaticHosting extends Construct {
     constructor(scope: Construct, id: string, props?: StaticHostingProps);
 }
 
+interface ProvisionDefaultWorkspaceLambdaProps {
+    /**
+     * DynamoDB data store table. Used for the Lambda's `DYNAMO_TABLE_NAME`
+     * env var and for granting the Lambda the writes + GSI queries it needs
+     * to provision default control-plane resources.
+     */
+    readonly dataStoreTable: ITable;
+    /**
+     * Control-plane event bus that the EventBridge Rule listens on.
+     */
+    readonly controlEventBus: IEventBus;
+}
+/**
+ * Lambda used by the user-onboarding workflow to create a user's default
+ * Tenant, Workspace, Memberships, and RoleAssignment.
+ *
+ * Owns the EventBridge Rule that routes the default-workspace onboarding
+ * event to itself, and the IAM permissions it needs on the data store
+ * table — colocating routing + permissions with the function they target.
+ */
+declare class ProvisionDefaultWorkspaceLambda extends Construct {
+    readonly lambda: NodejsFunction;
+    readonly rule: Rule;
+    constructor(scope: Construct, props: ProvisionDefaultWorkspaceLambdaProps);
+}
+
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/user-onboarding/user-onboarding-workflow.md
+ */
+interface UserOnboardingWorkflowProps {
+    readonly controlEventBus: IEventBus;
+    readonly dataStoreTable: ITable;
+}
+/**
+ * Control-plane workflow for onboarding users after Cognito confirmation.
+ */
+declare class UserOnboardingWorkflow extends Construct {
+    readonly provisionDefaultWorkspace: ProvisionDefaultWorkspaceLambda;
+    constructor(scope: Construct, props: UserOnboardingWorkflowProps);
+}
+
 /**
  * @see sites/www-docs/content/packages/@openhi/constructs/services/open-hi-auth-service.md
  */
@@ -935,7 +1119,7 @@ interface OpenHiAuthServiceProps extends OpenHiServiceProps {
  * @public
  */
 declare class OpenHiAuthService extends OpenHiService {
-    static readonly SERVICE_TYPE = "auth";
+    static readonly SERVICE_TYPE: "auth";
     /**
      * Returns an IUserPool by looking up the Auth stack's User Pool ID from SSM.
      */
@@ -970,6 +1154,7 @@ declare class OpenHiAuthService extends OpenHiService {
     readonly preTokenGenerationLambda: IFunction;
     readonly postAuthenticationLambda: IFunction;
     readonly postConfirmationLambda: IFunction;
+    readonly userOnboardingWorkflow: UserOnboardingWorkflow;
     readonly userPool: IUserPool;
     readonly userPoolClient: IUserPoolClient;
     readonly userPoolDomain: IUserPoolDomain;
@@ -986,6 +1171,7 @@ declare class OpenHiAuthService extends OpenHiService {
      * would collide.
      */
     private _dataStoreTable;
+    private _controlEventBus;
     constructor(ohEnv: OpenHiEnvironment, props?: OpenHiAuthServiceProps);
     /**
      * Creates the KMS key for the Cognito User Pool and exports its ARN to SSM.
@@ -1008,13 +1194,13 @@ declare class OpenHiAuthService extends OpenHiService {
     protected createPostAuthenticationLambda(): IFunction;
     /**
      * Creates the Post Confirmation Lambda (Cognito trigger). On sign-up
-     * confirmation, writes the new user's default Tenant, Workspace,
-     * Memberships, and `tenant-user` RoleAssignment, plus a User record
-     * carrying the Cognito `sub` and current tenant/workspace pointers
-     * (ADR 2026-03-17-01 invariants).
+     * confirmation, publishes a control-plane workflow event; provisioning lives
+     * behind EventBridge.
      */
     protected createPostConfirmationLambda(): IFunction;
+    protected createUserOnboardingWorkflow(): UserOnboardingWorkflow;
     private dataStoreTable;
+    private controlEventBus;
     /**
      * Creates the Cognito User Pool and exports its ID to SSM.
      * Look up via {@link OpenHiAuthService.userPoolFromConstruct}.
@@ -1046,9 +1232,8 @@ declare class OpenHiAuthService extends OpenHiService {
      */
     protected grantPostAuthenticationPermissions(): void;
     /**
-     * Grants the Post Confirmation Lambda write access to the data store
-     * table (and its GSIs) so it can seed the new user's Tenant, Workspace,
-     * Memberships, RoleAssignment, and User records on sign-up confirmation.
+     * Grants the Post Confirmation Lambda publish-only access to the
+     * control-plane event bus. Workflow Lambdas own DynamoDB writes.
      */
     protected grantPostConfirmationPermissions(): void;
     /**
@@ -1077,6 +1262,52 @@ declare class OpenHiAuthService extends OpenHiService {
     protected createUserPoolDomain(): IUserPoolDomain;
 }
 
+interface PlatformDeployBridgeLambdaProps {
+    /** Destination control event bus the bridge republishes onto. */
+    readonly controlEventBus: IEventBus;
+}
+/**
+ * Lambda that bridges CloudFormation Stack Status Change events from the
+ * default AWS bus into typed `platform.deployment-completed.v1` envelopes on
+ * the OpenHI control event bus.
+ *
+ * Owns its EventBridge Rule (on the default AWS bus) and the IAM
+ * permissions it needs — colocating routing + permissions with the
+ * function they target.
+ *
+ * The EventBridge rule pre-filters by stack-id prefix so the rule (and
+ * therefore the Lambda) only fires on the host stack's own branch deploys.
+ * This prevents cross-branch leak when multiple branches are deployed into
+ * the same account.
+ */
+declare class PlatformDeployBridgeLambda extends Construct {
+    readonly lambda: NodejsFunction;
+    readonly rule: Rule;
+    constructor(scope: Construct, props: PlatformDeployBridgeLambdaProps);
+}
+
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/platform-deploy-bridge/index.md
+ */
+interface PlatformDeployBridgeProps {
+    /** Destination control event bus the bridge republishes onto. */
+    readonly controlEventBus: IEventBus;
+}
+/**
+ * Source-side reactor that watches CloudFormation Stack Status Change
+ * events on the default AWS bus and republishes terminal-success events
+ * (`CREATE_COMPLETE` / `UPDATE_COMPLETE`) for OpenHi-tagged stacks onto
+ * the control event bus as `platform.deployment-completed.v1`.
+ *
+ * Implements row 4 of the workflow placement matrix
+ * (codedrifters/openhi#953): ops-plane reactor → republishes to
+ * control event bus.
+ */
+declare class PlatformDeployBridge extends Construct {
+    readonly bridgeLambda: PlatformDeployBridgeLambda;
+    constructor(scope: Construct, props: PlatformDeployBridgeProps);
+}
+
 /**
  * @see sites/www-docs/content/packages/@openhi/constructs/services/open-hi-global-service.md
  */
@@ -1084,12 +1315,12 @@ interface OpenHiGlobalServiceProps extends OpenHiServiceProps {
 }
 /**
  * Global Infrastructure stack: owns global DNS, certificates, and the
- * cross-region EventBridge buses (data, ops). Resources (root zone, optional
- * child zone, wildcard cert, data/ops buses) are created in protected methods;
- * subclasses may override to customize.
+ * cross-region EventBridge buses (data, ops, control). Resources (root zone,
+ * optional child zone, wildcard cert, data/ops/control buses) are created in
+ * protected methods; subclasses may override to customize.
  */
 declare class OpenHiGlobalService extends OpenHiService {
-    static readonly SERVICE_TYPE = "global";
+    static readonly SERVICE_TYPE: "global";
     /**
      * Returns an IHostedZone from the given attributes (no SSM). Use when the zone is imported from config.
      */
@@ -1113,6 +1344,19 @@ declare class OpenHiGlobalService extends OpenHiService {
      * Returns the ops event bus by name (deterministic per branch). Use from other stacks to obtain an IEventBus reference.
      */
     static opsEventBusFromConstruct(scope: Construct): IEventBus;
+    /**
+     * Returns the control-plane event bus by name (deterministic per branch). Use from other stacks to obtain an IEventBus reference.
+     */
+    static controlEventBusFromConstruct(scope: Construct): IEventBus;
+    /**
+     * Returns the workflow dedup table by name (deterministic per branch).
+     * Use from other stacks to obtain an ITable reference. Consumer Lambdas
+     * are typically wired via `WorkflowDedupTable.grantConsumer(fn, name)`
+     * on the owning service's `workflowDedupTable` reference; the
+     * `tableNameFromLookup` / `tableArnFromLookup` SSM helpers on the
+     * construct cover cross-stack consumers that need only the name/ARN.
+     */
+    static workflowDedupTableNameFromLookup(scope: Construct): string;
     get serviceType(): string;
     /** Override so this.props is typed with this service's options. */
     props: OpenHiGlobalServiceProps;
@@ -1129,6 +1373,23 @@ declare class OpenHiGlobalService extends OpenHiService {
      * Other stacks obtain it via {@link OpenHiGlobalService.opsEventBusFromConstruct}.
      */
     readonly opsEventBus: IEventBus;
+    /**
+     * Event bus for control-plane lifecycle and command events.
+     * Other stacks obtain it via {@link OpenHiGlobalService.controlEventBusFromConstruct}.
+     */
+    readonly controlEventBus: IEventBus;
+    /**
+     * Bridge that watches CloudFormation Stack Status Change events on the
+     * default AWS bus and republishes terminal-success events for OpenHi-tagged
+     * stacks onto {@link controlEventBus} as `platform.deployment-completed.v1`.
+     */
+    readonly platformDeployBridge: PlatformDeployBridge;
+    /**
+     * Shared dedup table every retryable workflow consumer dedupes against
+     * (TR-015). Singleton per deployment — provisioned here on the global
+     * stack so consumer stacks reach it via SSM lookups, not props.
+     */
+    readonly workflowDedupTable: WorkflowDedupTable;
     constructor(ohEnv: OpenHiEnvironment, props?: OpenHiGlobalServiceProps);
     /**
      * Validates that config required for the Global stack is present.
@@ -1162,6 +1423,22 @@ declare class OpenHiGlobalService extends OpenHiService {
      * Override to customize.
      */
     protected createOpsEventBus(): IEventBus;
+    /**
+     * Creates the control-plane event bus.
+     * Override to customize.
+     */
+    protected createControlEventBus(): IEventBus;
+    /**
+     * Creates the platform deploy bridge that republishes CloudFormation
+     * Stack Status Change events onto the control event bus.
+     * Override to customize.
+     */
+    protected createPlatformDeployBridge(): PlatformDeployBridge;
+    /**
+     * Creates the shared workflow dedup table (TR-015 singleton).
+     * Override to customize.
+     */
+    protected createWorkflowDedupTable(): WorkflowDedupTable;
 }
 
 /**
@@ -1184,7 +1461,7 @@ declare const REST_API_BASE_URL_SSM_NAME = "REST_API_BASE_URL";
  * Resources are created in protected methods; subclasses may override to customize.
  */
 declare class OpenHiRestApiService extends OpenHiService {
-    static readonly SERVICE_TYPE = "rest-api";
+    static readonly SERVICE_TYPE: "rest-api";
     /**
      * Returns an IHttpApi by looking up the REST API stack's HTTP API ID from SSM.
      */
@@ -1242,20 +1519,176 @@ declare class OpenHiRestApiService extends OpenHiService {
     protected createRootHttpApi(domainName: DomainName): RootHttpApi;
 }
 
+interface SeedDemoDataLambdaProps {
+    /**
+     * Data-store table the workflow upserts demo-data records into.
+     * Wired via `DYNAMO_TABLE_NAME` env var; granted scoped read on the
+     * Role PKs (pre-flight check) and scoped write on the enumerated
+     * demo Tenant / Workspace / Membership / RoleAssignment / User PKs.
+     */
+    readonly dataStoreTable: ITable;
+    /**
+     * Control event bus that re-publishes
+     * `platform.deployment-completed.v1` from the platform-deploy bridge.
+     * The Rule mounts here.
+     */
+    readonly controlEventBus: IEventBus;
+    /**
+     * Cognito User Pool the workflow provisions dev users into. The
+     * Lambda's IAM grant is scoped to this exact user-pool ARN — the
+     * grant uses the user-pool ARN, **not** the wildcard formatArn
+     * pattern used by `post-authentication-lambda` (that Lambda's
+     * trigger-driven dependency cycle does not apply here, so the
+     * tighter scope is safe).
+     */
+    readonly userPool: IUserPool;
+}
 /**
- * @see sites/www-docs/content/packages/@openhi/constructs/services/open-hi-data-service.md
+ * Lambda + EventBridge Rule pair for the seed-demo-data workflow.
+ * Owns the routing (`source` / `detail-type` pattern), the scoped
+ * DynamoDB grants, and the scoped Cognito Admin grant — co-locating
+ * routing + permissions with the function they target. Wiring to the
+ * workflow dedup table is the parent construct's job (it has the
+ * singleton reference) and happens via `WorkflowDedupTable.grantConsumer`.
+ *
+ * Stage-gating is the parent's job too — this construct itself never
+ * checks the stage. The CDK stage-router (`OpenHiDataService`)
+ * decides whether to instantiate it at all on each stage.
  */
-interface OpenHiDataServiceProps extends OpenHiServiceProps {
+declare class SeedDemoDataLambda extends Construct {
+    readonly lambda: NodejsFunction;
+    readonly rule: Rule;
+    constructor(scope: Construct, props: SeedDemoDataLambdaProps);
 }
+
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/seed-demo-data/seed-demo-data-workflow.md
+ */
+interface SeedDemoDataWorkflowProps {
+    /** Control event bus carrying `platform.system-data-seeded.v1`. */
+    readonly controlEventBus: IEventBus;
+    /** Data-store table the workflow upserts demo-data records into. */
+    readonly dataStoreTable: ITable;
+    /** Cognito User Pool the workflow provisions dev users into. */
+    readonly userPool: IUserPool;
+}
+/**
+ * Control-plane workflow that fires on every platform deploy and
+ * idempotently re-asserts the demo-data graph: placeholder tenant +
+ * workspace, 3 demo tenants + 4 workspaces, and per-dev-user Cognito
+ * users with their DynamoDB User records, Memberships, and
+ * RoleAssignments.
+ *
+ * Mounted on the data-service stack so the IAM grants against the
+ * data-store table stay local. The control event bus and the workflow
+ * dedup table reach in cross-stack via the SSM lookups
+ * `OpenHiGlobalService.controlEventBusFromConstruct` and
+ * `WorkflowDedupTable.grantConsumerFromLookup` respectively. The
+ * Cognito User Pool similarly reaches in via
+ * `OpenHiAuthService.userPoolFromConstruct`.
+ *
+ * Non-prod-only: the CDK stage-router (`OpenHiDataService`)
+ * conditionally constructs this workflow only on non-prod stages.
+ * The construct itself never checks the stage — its absence in prod
+ * stacks is the gate.
+ */
+declare class SeedDemoDataWorkflow extends Construct {
+    readonly seedDemoData: SeedDemoDataLambda;
+    constructor(scope: Construct, props: SeedDemoDataWorkflowProps);
+}
+
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/seed-system-data/events.md
+ */
+/**
+ * Stable logical name this workflow registers with the shared
+ * `WorkflowDedupTable` (TR-015). Used in both the construct grant
+ * (`workflowDedupTable.grantConsumer(lambda, SEED_SYSTEM_DATA_CONSUMER_NAME)`)
+ * and the handler's runtime `recordIfAbsent` call — keep them aligned by
+ * importing this constant in both places.
+ */
+declare const SEED_SYSTEM_DATA_CONSUMER_NAME = "seed-system-data";
+/**
+ * Free-form `actor.system` value the handler stamps on the
+ * `platform.system-data-seeded.v1` event it publishes when seeding
+ * completes. Pinned here so the test can assert the wire value without
+ * importing private handler internals.
+ */
+declare const SEED_SYSTEM_DATA_ACTOR_SYSTEM = "seed-system-data";
+/**
+ * Env var the Lambda construct injects with the control event bus
+ * name. The handler reads it to build the publisher target when
+ * emitting `platform.system-data-seeded.v1` after a successful seed.
+ */
+declare const SEED_SYSTEM_DATA_CONTROL_BUS_ENV_VAR = "CONTROL_EVENT_BUS_NAME";
+
+interface SeedSystemDataLambdaProps {
+    /**
+     * Data-store table the workflow upserts platform-singleton control-plane
+     * records into. Wired via `DYNAMO_TABLE_NAME` env var; granted scoped
+     * write permission to the role records' partition keys only.
+     */
+    readonly dataStoreTable: ITable;
+    /**
+     * Control event bus that re-publishes
+     * `platform.deployment-completed.v1` from the platform-deploy bridge.
+     * The Rule mounts here.
+     */
+    readonly controlEventBus: IEventBus;
+}
+/**
+ * Lambda + EventBridge Rule pair for the seed-system-data workflow. Owns
+ * the routing (`source` / `detail-type` pattern) and the scoped data-store
+ * grants — co-locating routing + permissions with the function they
+ * target. Wiring to the workflow dedup table is the parent construct's
+ * job (it has the singleton reference) and happens via
+ * `WorkflowDedupTable.grantConsumer`.
+ */
+declare class SeedSystemDataLambda extends Construct {
+    readonly lambda: NodejsFunction;
+    readonly rule: Rule;
+    constructor(scope: Construct, props: SeedSystemDataLambdaProps);
+}
+
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/seed-system-data/seed-system-data-workflow.md
+ */
+interface SeedSystemDataWorkflowProps {
+    /** Control event bus carrying `platform.deployment-completed.v1`. */
+    readonly controlEventBus: IEventBus;
+    /** Data-store table the workflow upserts platform-singleton records into. */
+    readonly dataStoreTable: ITable;
+}
+/**
+ * Control-plane workflow that fires on every platform deploy and
+ * idempotently re-asserts the platform-singleton control-plane records
+ * (today: the three canonical Roles; future: additional system data
+ * slotted in as sibling steps under the same dedup record).
+ *
+ * Mounted on the data-service stack so the IAM grants against the
+ * data-store table stay local. The control event bus and the
+ * workflow dedup table reach in cross-stack via the SSM lookups
+ * `OpenHiGlobalService.controlEventBusFromConstruct` and
+ * `WorkflowDedupTable.grantConsumerFromLookup` respectively.
+ */
+declare class SeedSystemDataWorkflow extends Construct {
+    readonly seedSystemData: SeedSystemDataLambda;
+    constructor(scope: Construct, props: SeedSystemDataWorkflowProps);
+}
+
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/services/open-hi-data-service.md
+ */
+type OpenHiDataServiceProps = OpenHiServiceProps;
 /**
  * Data storage service stack: centralizes DynamoDB, S3, and other persistence
  * resources for OpenHI. Creates the single-table data store in a protected
  * method; subclasses may override to customize. EventBridge event buses
- * (data, ops) are owned by {@link OpenHiGlobalService} so they deploy ahead of
- * regional services.
+ * (data, ops, control) are owned by {@link OpenHiGlobalService} so they deploy
+ * ahead of regional services.
  */
 declare class OpenHiDataService extends OpenHiService {
-    static readonly SERVICE_TYPE = "data";
+    static readonly SERVICE_TYPE: "data";
     /**
      * Returns the data store table by name. Use from other stacks (e.g. REST API Lambda) to obtain an ITable reference.
      */
@@ -1284,7 +1717,53 @@ declare class OpenHiDataService extends OpenHiService {
      * the read path is not wired up yet.
      */
     readonly dataStorePostgresReplica: DataStorePostgresReplica;
+    /**
+     * Deploy-triggered workflow that idempotently re-asserts the
+     * platform-singleton control-plane records (today: the three canonical
+     * Roles via `CONTROL_PLANE_ROLE_CONCEPTS`; future: additional system
+     * data). Subscribes to `platform.deployment-completed.v1` on the
+     * control event bus and dedups via the shared `WorkflowDedupTable`.
+     */
+    readonly seedSystemDataWorkflow: SeedSystemDataWorkflow;
+    /**
+     * Deploy-triggered workflow that idempotently re-asserts the demo
+     * data graph (placeholder + 3 demo Tenants + 5 Workspaces; per
+     * dev-user Cognito users with their DynamoDB User records,
+     * Memberships, and RoleAssignments). **Non-prod only** —
+     * `undefined` on prod stages. The synth-time stage gate in
+     * {@link createSeedDemoDataWorkflow} is the only guarantee
+     * separating prod stacks from the workflow's IAM grants and rule
+     * target; the construct itself never checks the stage.
+     */
+    readonly seedDemoDataWorkflow?: SeedDemoDataWorkflow;
+    /**
+     * Cached control-event-bus lookup. `OpenHiGlobalService.controlEventBusFromConstruct`
+     * registers a child `EventBus.fromEventBusName` construct with a
+     * fixed id under the scope it is passed, so calling it twice on the
+     * same `OpenHiDataService` instance collides. The cache mirrors the
+     * `private controlEventBus()` pattern already used in
+     * `OpenHiAuthService`. Use {@link controlEventBus} from this class
+     * — never call the static lookup from inside `OpenHiDataService`.
+     */
+    private _controlEventBus;
     constructor(ohEnv: OpenHiEnvironment, props?: OpenHiDataServiceProps);
+    /**
+     * Lazily looks up the control event bus exactly once per
+     * `OpenHiDataService` instance and caches the reference. Every
+     * workflow that consumes the bus must read it through this method
+     * — see {@link _controlEventBus} for the underlying collision risk.
+     */
+    private controlEventBus;
+    /**
+     * Creates the seed-system-data workflow. Override to customize.
+     */
+    protected createSeedSystemDataWorkflow(): SeedSystemDataWorkflow;
+    /**
+     * Creates the seed-demo-data workflow — but only on non-prod
+     * stages. Returns `undefined` on prod so the workflow literally
+     * does not exist in prod stacks. Override to customize.
+     */
+    protected createSeedDemoDataWorkflow(): SeedDemoDataWorkflow | undefined;
     /**
      * Creates the single-table DynamoDB data store.
      * Override to customize.
@@ -1300,7 +1779,7 @@ interface OpenHiGraphqlServiceProps extends OpenHiServiceProps {
  * {@link OpenHiGraphqlService.graphqlApiFromConstruct}.
  */
 declare class OpenHiGraphqlService extends OpenHiService {
-    static readonly SERVICE_TYPE = "graphql-api";
+    static readonly SERVICE_TYPE: "graphql-api";
     /**
      * Returns the GraphQL API by looking up the GraphQL stack's API ID from SSM.
      * Use from other stacks to obtain an IGraphqlApi reference.
@@ -1314,4 +1793,4 @@ declare class OpenHiGraphqlService extends OpenHiService {
     protected createRootGraphqlApi(): RootGraphqlApi;
 }
 
-export { type BuildParameterNameProps, ChildHostedZone, type ChildHostedZoneProps, CognitoFixtureSeederClient, type CognitoFixtureSeederClientProps, CognitoUserPool, CognitoUserPoolClient, CognitoUserPoolDomain, CognitoUserPoolKmsKey, DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES, DATA_STORE_CHANGE_DETAIL_TYPE, DATA_STORE_CHANGE_EVENT_SOURCE, DataEventBus, DataStoreHistoricalArchive, type DataStoreHistoricalArchiveProps, DataStorePostgresReplica, type DataStorePostgresReplicaProps, DiscoverableStringParameter, type DiscoverableStringParameterProps, DynamoDbDataStore, type DynamoDbDataStoreProps, type FhirCurrentResourceChangeDetail, OpenHiApp, type OpenHiAppProps, OpenHiAuthService, type OpenHiAuthServiceProps, OpenHiDataService, type OpenHiDataServiceProps, OpenHiEnvironment, type OpenHiEnvironmentProps, OpenHiGlobalService, type OpenHiGlobalServiceProps, OpenHiGraphqlService, type OpenHiGraphqlServiceProps, OpenHiRestApiService, type OpenHiRestApiServiceProps, OpenHiService, type OpenHiServiceProps, type OpenHiServiceType, OpenHiStage, type OpenHiStageProps, OpsEventBus, POSTGRES_REPLICA_CLUSTER_ARN_SSM_NAME, POSTGRES_REPLICA_DATABASE_NAME_SSM_NAME, POSTGRES_REPLICA_SECRET_ARN_SSM_NAME, PostAuthenticationLambda, PostConfirmationLambda, type PostConfirmationLambdaProps, PreTokenGenerationLambda, type PreTokenGenerationLambdaProps, REST_API_BASE_URL_SSM_NAME, RootGraphqlApi, type RootGraphqlApiProps, RootHostedZone, RootHttpApi, type RootHttpApiProps, RootWildcardCertificate, STATIC_HOSTING_SERVICE_TYPE, StaticHosting, type StaticHostingProps, buildFhirCurrentResourceChangeDetail, getDynamoDbDataStoreTableName, getPostgresReplicaSchemaName };
+export { type BuildParameterNameProps, ChildHostedZone, type ChildHostedZoneProps, CognitoFixtureSeederClient, type CognitoFixtureSeederClientProps, CognitoUserPool, CognitoUserPoolClient, CognitoUserPoolDomain, CognitoUserPoolKmsKey, ControlEventBus, DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES, DATA_STORE_CHANGE_DETAIL_TYPE, DATA_STORE_CHANGE_EVENT_SOURCE, DataEventBus, DataStoreHistoricalArchive, type DataStoreHistoricalArchiveProps, DataStorePostgresReplica, type DataStorePostgresReplicaProps, DiscoverableStringParameter, type DiscoverableStringParameterProps, DynamoDbDataStore, type DynamoDbDataStoreProps, type FhirCurrentResourceChangeDetail, type GrantConsumerOptions, OPENHI_TAG_SUFFIX_BRANCH_NAME, OPENHI_TAG_SUFFIX_REPO_NAME, OPENHI_TAG_SUFFIX_SERVICE_TYPE, OPENHI_TAG_SUFFIX_STAGE_TYPE, OpenHiApp, type OpenHiAppProps, OpenHiAuthService, type OpenHiAuthServiceProps, OpenHiDataService, type OpenHiDataServiceProps, OpenHiEnvironment, type OpenHiEnvironmentProps, OpenHiGlobalService, type OpenHiGlobalServiceProps, OpenHiGraphqlService, type OpenHiGraphqlServiceProps, OpenHiRestApiService, type OpenHiRestApiServiceProps, OpenHiService, type OpenHiServiceProps, type OpenHiServiceType, OpenHiStage, type OpenHiStageProps, OpsEventBus, POSTGRES_REPLICA_CLUSTER_ARN_SSM_NAME, POSTGRES_REPLICA_DATABASE_NAME_SSM_NAME, POSTGRES_REPLICA_SECRET_ARN_SSM_NAME, PlatformDeployBridge, PlatformDeployBridgeLambda, type PlatformDeployBridgeLambdaProps, type PlatformDeployBridgeProps, PostAuthenticationLambda, PostConfirmationLambda, type PostConfirmationLambdaProps, PreTokenGenerationLambda, type PreTokenGenerationLambdaProps, ProvisionDefaultWorkspaceLambda, type ProvisionDefaultWorkspaceLambdaProps, REST_API_BASE_URL_SSM_NAME, RootGraphqlApi, type RootGraphqlApiProps, RootHostedZone, RootHttpApi, type RootHttpApiProps, RootWildcardCertificate, SEED_SYSTEM_DATA_ACTOR_SYSTEM, SEED_SYSTEM_DATA_CONSUMER_NAME, SEED_SYSTEM_DATA_CONTROL_BUS_ENV_VAR, STATIC_HOSTING_SERVICE_TYPE, SeedDemoDataLambda, type SeedDemoDataLambdaProps, SeedDemoDataWorkflow, type SeedDemoDataWorkflowProps, SeedSystemDataLambda, type SeedSystemDataLambdaProps, SeedSystemDataWorkflow, type SeedSystemDataWorkflowProps, StaticHosting, type StaticHostingProps, UserOnboardingWorkflow, type UserOnboardingWorkflowProps, WorkflowDedupConsumerNameInvalidError, WorkflowDedupTable, WorkflowDedupTableDuplicateError, type WorkflowDedupTableProps, buildFhirCurrentResourceChangeDetail, getDynamoDbDataStoreTableName, getPostgresReplicaSchemaName, getWorkflowDedupTableName, openHiTagKey };