@openhi/constructs 0.0.105 → 0.0.106

package/lib/index.d.ts

@@ -14,13 +14,15 @@ 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 { IFunction, Function } 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';
+import { ControlPlaneRoleCode } from '@openhi/types';
 import { PostConfirmationTriggerEvent } from 'aws-lambda';
+export { PlatformDeploymentCompletedV1, PlatformSystemDataSeededV1 } from '@openhi/workflows';
 
 /*******************************************************************************
  *
@@ -119,6 +121,253 @@ interface DynamoDbStreamKinesisRecord {
     };
 }
 
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/platform-deploy-bridge/index.md
+ */
+/** EventBridge `source` for the AWS-native CloudFormation events the bridge listens to. */
+declare const CLOUDFORMATION_EVENT_SOURCE: "aws.cloudformation";
+/** EventBridge `detail-type` for terminal stack status events. */
+declare const CLOUDFORMATION_STACK_STATUS_CHANGE_DETAIL_TYPE: "CloudFormation Stack Status Change";
+/** Stack statuses the bridge republishes. Other statuses are pre-filtered at the rule. */
+declare const BRIDGED_STATUSES: readonly ["CREATE_COMPLETE", "UPDATE_COMPLETE"];
+type BridgedStatus = (typeof BRIDGED_STATUSES)[number];
+/** Env var the bridge handler reads to discover the control event bus name. */
+declare const CONTROL_EVENT_BUS_NAME_ENV_VAR = "CONTROL_EVENT_BUS_NAME";
+/**
+ * Env var the bridge handler reads for the resolved
+ * `openhi:repo-name`-shaped tag key. Resolved at synth time from the host
+ * stack's `appName` + {@link OPENHI_TAG_SUFFIX_REPO_NAME}.
+ */
+declare const OPENHI_REPO_TAG_KEY_ENV_VAR = "OPENHI_REPO_TAG_KEY";
+/**
+ * Env var the bridge handler reads for the resolved `openhi:` tag prefix.
+ * Resolved at synth time from the host stack's `appName`. Used to project
+ * the relevant stack tags into the published envelope.
+ */
+declare const OPENHI_TAG_KEY_PREFIX_ENV_VAR = "OPENHI_TAG_KEY_PREFIX";
+/** Free-form `actor.system` value per TR-016 § Decision points #1 (bootstrap-role pattern). */
+declare const PLATFORM_DEPLOY_BRIDGE_ACTOR_SYSTEM = "platform-deploy-bridge";
+/**
+ * Subset of the CloudFormation Stack Status Change `detail` field the
+ * bridge handler reads. AWS-side schema lives at
+ * <https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/monitoring-cloudformation.html>.
+ */
+interface CloudFormationStackStatusChangeDetail {
+    readonly "stack-id": string;
+    readonly "logical-resource-id"?: string;
+    readonly "physical-resource-id"?: string;
+    readonly "status-details": {
+        readonly status: string;
+        readonly "status-reason"?: string;
+    };
+    readonly "resource-type"?: string;
+    readonly "client-request-token"?: string;
+}
+
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/seed-demo-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_DEMO_DATA_CONSUMER_NAME)`)
+ * and the handler's runtime `recordIfAbsent` call — keep them aligned by
+ * importing this constant in both places.
+ */
+declare const SEED_DEMO_DATA_CONSUMER_NAME = "seed-demo-data";
+/** FHIR `Identifier.system` for the demo-scenario URN scheme. */
+declare const DEMO_URN_SYSTEM = "urn:openhi:demo";
+/**
+ * FHIR `Identifier.system` for the canonical OpenHI resource URN
+ * (ADR 2026-03-12-01). The value form is
+ * `urn:ohi:<tenantId>:<workspaceId>:<resourceType>:<id>`; empty
+ * workspaceId means the resource has tenant-wide scope (or is itself
+ * the workspace identity, in the Workspace case).
+ */
+declare const OPENHI_RESOURCE_URN_SYSTEM = "http://openhi.org/";
+/**
+ * Period stamped on every demo Membership and RoleAssignment. Fixed
+ * start so re-runs produce byte-identical bodies (decision #4); no
+ * end so demo memberships are open-ended.
+ */
+declare const DEMO_PERIOD: {
+    readonly start: "2026-01-01T00:00:00Z";
+};
+/**
+ * Sentinel `tenantId` used on every dev user's `system-admin`
+ * RoleAssignment. A `system-admin` RA is platform-scoped (it spans
+ * every tenant), but the RoleAssignment entity requires a tenantId on
+ * its key for sharding — there is no real tenant to point at. The
+ * `"platform"` literal is a reserved value that never matches a real
+ * Tenant id and signals "this RA scopes across all tenants".
+ *
+ * Renaming this constant is a wire-format break — the IAM grant in
+ * `seed-demo-data-lambda.ts` enumerates exact-match `LeadingKeys`
+ * computed from this value, and the in-band records written under it
+ * become unreachable if the sentinel changes.
+ */
+declare const PLATFORM_SCOPE_TENANT_ID = "platform";
+/** Placeholder Tenant id seeded by the workflow as the dev-user `currentTenant`. */
+declare const PLACEHOLDER_TENANT_ID = "placeholder-tenant-id";
+/** Placeholder Workspace id seeded by the workflow as the dev-user `currentWorkspace`. */
+declare const PLACEHOLDER_WORKSPACE_ID = "placeholder-workspace-id";
+/**
+ * Dev-user descriptor. Every entry produces:
+ *   - one Cognito user (idempotent create-then-skip),
+ *   - one DynamoDB User record (id = `dev-<email-local-part>`),
+ *   - four Memberships (placeholder + the three demo tenants),
+ *   - four `tenant-admin` RoleAssignments (one per tenant the user
+ *     belongs to),
+ *   - one `system-admin` RoleAssignment scoped to {@link PLATFORM_SCOPE_TENANT_ID}.
+ */
+interface DemoDevUser {
+    /** Stable DynamoDB User id. */
+    readonly id: string;
+    /** Email used as the Cognito `Username` and as the seed for the password algorithm. */
+    readonly email: string;
+}
+/**
+ * Hardcoded dev-user roster. Adding a new developer is a one-line
+ * change here plus a re-deploy. The list intentionally lives in-source
+ * (not behind an env-var seam) so the IAM grant in
+ * `seed-demo-data-lambda.ts` can enumerate per-user PKs at synth time.
+ */
+declare const DEV_USERS: ReadonlyArray<DemoDevUser>;
+/**
+ * A single workspace inside a demo tenant. The mixed tenant has two
+ * workspaces (wound-care and primary-care sub-workspaces); the other
+ * two tenants have one each.
+ */
+interface DemoWorkspaceSpec {
+    /** Stable id (DynamoDB record id; also drives the canonical OHI URN). */
+    readonly id: string;
+    /** FHIR `Workspace.name`. */
+    readonly name: string;
+    /**
+     * Role suffix used in the demo URN value (`<scenario>:<roleSuffix>`).
+     * Mirrors seed-fixtures' role suffix convention: `workspace` for
+     * single-workspace tenants, `workspace-<sub>` for the mixed tenant.
+     */
+    readonly roleSuffix: string;
+}
+/**
+ * One demo tenant + the workspaces it owns. Re-exported via {@link
+ * DEMO_TENANT_SPECS} as the canonical list; iterate that constant in
+ * the handler and the IAM-grant builder so the value sets agree.
+ */
+interface DemoTenantSpec {
+    /**
+     * Scenario slug — `placeholder`, `demo-wound-care`, `demo-primary-care`,
+     * `demo-mixed`. The placeholder tenant's slug is `placeholder`; the
+     * three demo tenants mirror seed-fixtures' `fixture-*` slugs renamed
+     * to `demo-*`.
+     */
+    readonly scenario: string;
+    /** Stable id (DynamoDB record id; also drives the canonical OHI URN). */
+    readonly tenantId: string;
+    /** FHIR `Tenant.name`. */
+    readonly tenantName: string;
+    /** Workspaces owned by this tenant. */
+    readonly workspaces: ReadonlyArray<DemoWorkspaceSpec>;
+}
+/**
+ * The full demo-tenant graph. Four entries: the placeholder tenant the
+ * JWT-claim fallback resolves to, plus the three v1 demo scenarios
+ * (OPS-009 §"v1 scenarios"):
+ *
+ *   0. Placeholder tenant — dereferences the JWT-claim fallback in
+ *      `pre-token-generation.handler.ts` and acts as every dev user's
+ *      `currentTenant`/`currentWorkspace` so Post-Confirmation skips
+ *      default provisioning when a seeded User signs in.
+ *   1. Single-workspace wound-care tenant.
+ *   2. Single-workspace primary-care tenant.
+ *   3. Two-workspace mixed tenant — exercises the cross-workspace
+ *      isolation flow that single-workspace tenants cannot.
+ */
+declare const DEMO_TENANT_SPECS: ReadonlyArray<DemoTenantSpec>;
+/** Stable Membership id derived from `(devUserId, tenantId)`. */
+declare const demoMembershipId: (devUserId: string, tenantId: string) => string;
+/**
+ * Stable RoleAssignment id derived from `(devUserId, tenantId, roleCode)`.
+ * Each (user, tenant, role) tuple maps to exactly one record — re-runs
+ * upsert the same id.
+ */
+declare const demoRoleAssignmentId: (devUserId: string, tenantId: string, roleCode: ControlPlaneRoleCode) => string;
+/**
+ * Demo-scenario FHIR `Identifier` entry — `urn:openhi:demo:<scenario>:<role>`.
+ * Mirrors the `urn:openhi:fixture:<scenario>:<role>` pattern from
+ * `@openhi/seed-fixtures/src/urn.ts`, renamed to the `demo` namespace.
+ */
+declare const demoScenarioIdentifier: (scenario: string, roleSuffix: string) => {
+    system: string;
+    value: string;
+};
+/**
+ * Canonical OpenHI resource FHIR `Identifier` entry per ADR
+ * 2026-03-12-01. `workspaceId` is empty for both Tenant resources and
+ * Workspace resources — for a Tenant, the resource is tenant-scoped
+ * with no workspace context; for a Workspace, the resource IS the
+ * workspace identity rather than living inside one.
+ */
+declare const openhiResourceIdentifier: (params: {
+    tenantId: string;
+    workspaceId: string;
+    resourceType: string;
+    id: string;
+}) => {
+    use: string;
+    system: string;
+    value: string;
+};
+/**
+ * Roles every dev user holds in every tenant they belong to. Per scope
+ * decision Q3, every dev user is `tenant-admin` in every tenant — there
+ * is no per-(user, tenant) variance to drive from.
+ */
+declare const demoRolesForUserInTenant: (_user: DemoDevUser, _tenantId: string) => ReadonlyArray<ControlPlaneRoleCode>;
+/**
+ * DynamoDB single-table partition-key builders. The IAM grant in
+ * `seed-demo-data-lambda.ts` uses these to enumerate exact-match
+ * `dynamodb:LeadingKeys` values; the entity definitions in
+ * `data/dynamo/entities/control/` own the canonical key templates.
+ *
+ * These builders MUST emit the keys ElectroDB actually writes — not
+ * the entity definition's pretty template. None of the control-plane
+ * entities sets `casing: "none"` on the base-table PK template, so
+ * ElectroDB applies its default lowercase casing at runtime: the
+ * entity's `ROLE#ID#${id}` becomes `role#id#<id>` on the wire. A
+ * builder that returns the uppercase template form produces a
+ * silently-broken IAM grant (every PutItem denied with "no
+ * identity-based policy allows" because the request's leading-key
+ * never matches a policy value).
+ */
+declare const rolePartitionKey: (roleId: string) => string;
+declare const demoTenantPartitionKey: (tenantId: string) => string;
+declare const demoWorkspacePartitionKey: (tenantId: string, workspaceId: string) => string;
+declare const demoMembershipPartitionKey: (tenantId: string, membershipId: string) => string;
+declare const demoRoleAssignmentPartitionKey: (tenantId: string, roleAssignmentId: string) => string;
+/** User entity PK template — `USER#ID#<id>` → `user#id#<id>` on the wire. */
+declare const demoUserPartitionKey: (userId: string) => string;
+/**
+ * Tenant + Workspace PKs the workflow writes on every fire: the 4
+ * tenant PKs (placeholder + 3 demo) plus their workspaces (1 + 1 + 1 + 2 = 5).
+ */
+declare const demoBasePartitionKeys: () => ReadonlyArray<string>;
+/**
+ * Membership + RoleAssignment + User PKs the workflow writes per dev
+ * user. Empty when `devUsers` is empty (used by tests). The list
+ * mirrors the handler's iteration order so the IAM grant covers every
+ * write the handler can make.
+ *
+ * Per dev user the function emits:
+ *   - one User PK,
+ *   - per tenant in {@link DEMO_TENANT_SPECS}: one Membership PK plus
+ *     one `tenant-admin` RoleAssignment PK,
+ *   - one platform-scoped `system-admin` RoleAssignment PK keyed by
+ *     {@link PLATFORM_SCOPE_TENANT_ID}.
+ */
+declare const demoDevUserPartitionKeys: (devUsers: ReadonlyArray<DemoDevUser>) => ReadonlyArray<string>;
+
 /**
  * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/user-onboarding/events.md
  */
@@ -353,6 +602,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.
  *
@@ -745,6 +1016,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
  */
@@ -1105,7 +1478,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.
      */
@@ -1248,6 +1621,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
  */
@@ -1260,7 +1679,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.
      */
@@ -1288,6 +1707,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;
@@ -1309,6 +1737,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.
@@ -1347,6 +1787,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;
 }
 
 /**
@@ -1369,7 +1820,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.
      */
@@ -1427,11 +1878,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.
+ */
+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.
  */
-interface OpenHiDataServiceProps extends OpenHiServiceProps {
+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
@@ -1440,7 +2047,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.
      */
@@ -1469,7 +2076,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.
@@ -1485,7 +2138,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.
@@ -1499,5 +2152,5 @@ declare class OpenHiGraphqlService extends OpenHiService {
     protected createRootGraphqlApi(): RootGraphqlApi;
 }
 
-export { ChildHostedZone, CognitoFixtureSeederClient, CognitoUserPool, CognitoUserPoolClient, CognitoUserPoolDomain, CognitoUserPoolKmsKey, ControlEventBus, DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES, DATA_STORE_CHANGE_DETAIL_TYPE, DATA_STORE_CHANGE_EVENT_SOURCE, DataEventBus, DataStoreHistoricalArchive, DataStorePostgresReplica, DiscoverableStringParameter, DynamoDbDataStore, OpenHiApp, OpenHiAuthService, OpenHiDataService, OpenHiEnvironment, OpenHiGlobalService, OpenHiGraphqlService, OpenHiRestApiService, OpenHiService, OpenHiStage, OpsEventBus, POSTGRES_REPLICA_CLUSTER_ARN_SSM_NAME, POSTGRES_REPLICA_DATABASE_NAME_SSM_NAME, POSTGRES_REPLICA_SECRET_ARN_SSM_NAME, PROVISION_DEFAULT_WORKSPACE_DETAIL_TYPE, PostAuthenticationLambda, PostConfirmationLambda, PreTokenGenerationLambda, ProvisionDefaultWorkspaceLambda, REST_API_BASE_URL_SSM_NAME, RootGraphqlApi, RootHostedZone, RootHttpApi, RootWildcardCertificate, STATIC_HOSTING_SERVICE_TYPE, StaticHosting, USER_ONBOARDING_EVENT_SOURCE, UserOnboardingWorkflow, buildFhirCurrentResourceChangeDetail, buildProvisionDefaultWorkspaceRequestedDetail, getDynamoDbDataStoreTableName, getPostgresReplicaSchemaName };
-export type { BuildParameterNameProps, ChildHostedZoneProps, CognitoFixtureSeederClientProps, DataStoreHistoricalArchiveProps, DataStorePostgresReplicaProps, DiscoverableStringParameterProps, DynamoDbDataStoreProps, FhirCurrentResourceChangeDetail, OpenHiAppProps, OpenHiAuthServiceProps, OpenHiDataServiceProps, OpenHiEnvironmentProps, OpenHiGlobalServiceProps, OpenHiGraphqlServiceProps, OpenHiRestApiServiceProps, OpenHiServiceProps, OpenHiServiceType, OpenHiStageProps, PostConfirmationLambdaProps, PreTokenGenerationLambdaProps, ProvisionDefaultWorkspaceLambdaProps, ProvisionDefaultWorkspaceRequestedDetail, RootGraphqlApiProps, RootHttpApiProps, StaticHostingProps, UserOnboardingWorkflowProps };
+export { BRIDGED_STATUSES, CLOUDFORMATION_EVENT_SOURCE, CLOUDFORMATION_STACK_STATUS_CHANGE_DETAIL_TYPE, CONTROL_EVENT_BUS_NAME_ENV_VAR, ChildHostedZone, CognitoFixtureSeederClient, CognitoUserPool, CognitoUserPoolClient, CognitoUserPoolDomain, CognitoUserPoolKmsKey, ControlEventBus, DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES, DATA_STORE_CHANGE_DETAIL_TYPE, DATA_STORE_CHANGE_EVENT_SOURCE, DEMO_PERIOD, DEMO_TENANT_SPECS, DEMO_URN_SYSTEM, DEV_USERS, DataEventBus, DataStoreHistoricalArchive, DataStorePostgresReplica, DiscoverableStringParameter, DynamoDbDataStore, OPENHI_REPO_TAG_KEY_ENV_VAR, OPENHI_RESOURCE_URN_SYSTEM, OPENHI_TAG_KEY_PREFIX_ENV_VAR, OPENHI_TAG_SUFFIX_BRANCH_NAME, OPENHI_TAG_SUFFIX_REPO_NAME, OPENHI_TAG_SUFFIX_SERVICE_TYPE, OPENHI_TAG_SUFFIX_STAGE_TYPE, OpenHiApp, OpenHiAuthService, OpenHiDataService, OpenHiEnvironment, OpenHiGlobalService, OpenHiGraphqlService, OpenHiRestApiService, OpenHiService, OpenHiStage, OpsEventBus, PLACEHOLDER_TENANT_ID, PLACEHOLDER_WORKSPACE_ID, PLATFORM_DEPLOY_BRIDGE_ACTOR_SYSTEM, PLATFORM_SCOPE_TENANT_ID, POSTGRES_REPLICA_CLUSTER_ARN_SSM_NAME, POSTGRES_REPLICA_DATABASE_NAME_SSM_NAME, POSTGRES_REPLICA_SECRET_ARN_SSM_NAME, PROVISION_DEFAULT_WORKSPACE_DETAIL_TYPE, PlatformDeployBridge, PlatformDeployBridgeLambda, PostAuthenticationLambda, PostConfirmationLambda, PreTokenGenerationLambda, ProvisionDefaultWorkspaceLambda, REST_API_BASE_URL_SSM_NAME, RootGraphqlApi, RootHostedZone, RootHttpApi, RootWildcardCertificate, SEED_DEMO_DATA_CONSUMER_NAME, SEED_SYSTEM_DATA_ACTOR_SYSTEM, SEED_SYSTEM_DATA_CONSUMER_NAME, SEED_SYSTEM_DATA_CONTROL_BUS_ENV_VAR, STATIC_HOSTING_SERVICE_TYPE, SeedDemoDataLambda, SeedDemoDataWorkflow, SeedSystemDataLambda, SeedSystemDataWorkflow, StaticHosting, USER_ONBOARDING_EVENT_SOURCE, UserOnboardingWorkflow, WorkflowDedupConsumerNameInvalidError, WorkflowDedupTable, WorkflowDedupTableDuplicateError, buildFhirCurrentResourceChangeDetail, buildProvisionDefaultWorkspaceRequestedDetail, demoBasePartitionKeys, demoDevUserPartitionKeys, demoMembershipId, demoMembershipPartitionKey, demoRoleAssignmentId, demoRoleAssignmentPartitionKey, demoRolesForUserInTenant, demoScenarioIdentifier, demoTenantPartitionKey, demoUserPartitionKey, demoWorkspacePartitionKey, getDynamoDbDataStoreTableName, getPostgresReplicaSchemaName, getWorkflowDedupTableName, openHiTagKey, openhiResourceIdentifier, rolePartitionKey };
+export type { BridgedStatus, BuildParameterNameProps, ChildHostedZoneProps, CloudFormationStackStatusChangeDetail, CognitoFixtureSeederClientProps, DataStoreHistoricalArchiveProps, DataStorePostgresReplicaProps, DemoDevUser, DemoTenantSpec, DemoWorkspaceSpec, DiscoverableStringParameterProps, DynamoDbDataStoreProps, FhirCurrentResourceChangeDetail, GrantConsumerOptions, OpenHiAppProps, OpenHiAuthServiceProps, OpenHiDataServiceProps, OpenHiEnvironmentProps, OpenHiGlobalServiceProps, OpenHiGraphqlServiceProps, OpenHiRestApiServiceProps, OpenHiServiceProps, OpenHiServiceType, OpenHiStageProps, PlatformDeployBridgeLambdaProps, PlatformDeployBridgeProps, PostConfirmationLambdaProps, PreTokenGenerationLambdaProps, ProvisionDefaultWorkspaceLambdaProps, ProvisionDefaultWorkspaceRequestedDetail, RootGraphqlApiProps, RootHttpApiProps, SeedDemoDataLambdaProps, SeedDemoDataWorkflowProps, SeedSystemDataLambdaProps, SeedSystemDataWorkflowProps, StaticHostingProps, UserOnboardingWorkflowProps, WorkflowDedupTableProps };