@openhi/constructs 0.0.105 → 0.0.107

package/lib/index.d.mts

@@ -15,14 +15,18 @@ 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-DPodvl07.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';
 
 /**
@@ -239,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.
  *
@@ -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
  */
@@ -991,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.
      */
@@ -1134,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
  */
@@ -1146,7 +1320,7 @@ interface OpenHiGlobalServiceProps extends OpenHiServiceProps {
  * 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.
      */
@@ -1174,6 +1348,15 @@ declare class OpenHiGlobalService extends OpenHiService {
      * 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;
@@ -1195,6 +1378,18 @@ declare class OpenHiGlobalService extends OpenHiService {
      * 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.
@@ -1233,6 +1428,17 @@ declare class OpenHiGlobalService extends OpenHiService {
      * 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;
 }
 
 /**
@@ -1255,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.
      */
@@ -1313,11 +1519,167 @@ 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
@@ -1326,7 +1688,7 @@ interface OpenHiDataServiceProps extends OpenHiServiceProps {
  * 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.
      */
@@ -1355,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 `PLATFORM_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.
@@ -1371,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.
@@ -1385,4 +1793,4 @@ declare class OpenHiGraphqlService extends OpenHiService {
     protected createRootGraphqlApi(): RootGraphqlApi;
 }
 
-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, 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, ProvisionDefaultWorkspaceLambda, type ProvisionDefaultWorkspaceLambdaProps, REST_API_BASE_URL_SSM_NAME, RootGraphqlApi, type RootGraphqlApiProps, RootHostedZone, RootHttpApi, type RootHttpApiProps, RootWildcardCertificate, STATIC_HOSTING_SERVICE_TYPE, StaticHosting, type StaticHostingProps, UserOnboardingWorkflow, type UserOnboardingWorkflowProps, 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 };