@openhi/constructs 0.0.85 → 0.0.86

package/lib/firehose-archive-transform.handler.mjs

@@ -1,295 +1,10 @@
 import {
-  DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES,
-  DATA_STORE_CHANGE_DETAIL_TYPE,
-  DATA_STORE_CHANGE_EVENT_SOURCE,
-  buildFhirCurrentResourceChangeDetail,
-  dynamodbImageToPlain
-} from "./chunk-SWSN6GDD.mjs";
+  handler,
+  parseCurrentResourceKeys,
+  shouldDropAsGlobalTableReplicationRecord
+} from "./chunk-X5MHU7DA.mjs";
+import "./chunk-CEOAGPYY.mjs";
 import "./chunk-LZOMFHX3.mjs";
-
-// src/components/dynamodb/firehose-archive-transform.handler.ts
-import { randomUUID } from "crypto";
-import {
-  EventBridgeClient,
-  PutEventsCommand
-} from "@aws-sdk/client-eventbridge";
-import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
-var CURRENT_SK = "CURRENT";
-var PK_PATTERN = /^TID#(?<tenantId>[^#]+)#WID#(?<workspaceId>[^#]+)#RT#(?<resourceType>[^#]+)#ID#(?<resourceId>.+)$/;
-var AWS_REP_UPDATE_REGION = "aws:rep:updateregion";
-function getDynamoDbStringAttr(image, name) {
-  if (!image) {
-    return void 0;
-  }
-  const av = image[name];
-  if (typeof av?.S === "string" && av.S.trim() !== "") {
-    return av.S.trim();
-  }
-  return void 0;
-}
-function primaryImageForReplicationCheck(record) {
-  if (record.eventName === "REMOVE") {
-    return record.dynamodb?.OldImage;
-  }
-  return record.dynamodb?.NewImage;
-}
-function shouldDropAsGlobalTableReplicationRecord(record, archiveLambdaRegion) {
-  const image = primaryImageForReplicationCheck(record);
-  const updateRegion = getDynamoDbStringAttr(image, AWS_REP_UPDATE_REGION);
-  if (updateRegion && archiveLambdaRegion && updateRegion !== archiveLambdaRegion) {
-    return true;
-  }
-  return isDynamoDbReplicationUserIdentity(record.userIdentity);
-}
-function isDynamoDbReplicationUserIdentity(userIdentity) {
-  if (!userIdentity || typeof userIdentity !== "object") {
-    return false;
-  }
-  const ui = userIdentity;
-  const principalRaw = ui.principalId ?? ui.PrincipalId;
-  const typeRaw = ui.type ?? ui.Type;
-  const principal = typeof principalRaw === "string" ? principalRaw.toLowerCase() : "";
-  const type = typeof typeRaw === "string" ? typeRaw.toLowerCase() : "";
-  if (type === "service" && principal === "dynamodb.amazonaws.com") {
-    return false;
-  }
-  const replicationMarkers = [
-    "awsservicerolefordynamodbreplication",
-    "replication.dynamodb.amazonaws.com"
-  ];
-  return replicationMarkers.some((m) => principal.includes(m));
-}
-function parseCurrentResourceKeys(record) {
-  const keys = record.dynamodb?.Keys;
-  if (!keys) {
-    return null;
-  }
-  const pkAttr = keys.PK?.S;
-  const skAttr = keys.SK?.S;
-  if (!pkAttr || skAttr !== CURRENT_SK) {
-    return null;
-  }
-  const m = PK_PATTERN.exec(pkAttr);
-  if (!m?.groups) {
-    return null;
-  }
-  const { tenantId, workspaceId, resourceType, resourceId } = m.groups;
-  const image = record.eventName === "REMOVE" ? record.dynamodb?.OldImage : record.dynamodb?.NewImage;
-  if (!image) {
-    return null;
-  }
-  const plain = dynamodbImageToPlain(image);
-  const version = typeof plain.vid === "string" ? plain.vid : null;
-  if (!version) {
-    return null;
-  }
-  return { tenantId, workspaceId, resourceType, resourceId, version };
-}
-function partitionToken(value) {
-  if (!value || value.trim() === "") {
-    return "-";
-  }
-  return value.replace(/[/\\]/g, "_");
-}
-function buildArchivePayload(record, keys) {
-  const newImage = record.dynamodb?.NewImage;
-  const oldImage = record.dynamodb?.OldImage;
-  const resourceImage = record.eventName === "REMOVE" ? oldImage : newImage;
-  const resourcePlain = resourceImage ? dynamodbImageToPlain(resourceImage) : {};
-  if (typeof resourcePlain.resource === "string") {
-    try {
-      resourcePlain.resource = JSON.parse(resourcePlain.resource);
-    } catch {
-    }
-  }
-  return {
-    eventName: record.eventName,
-    archivedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    tenantId: keys.tenantId,
-    workspaceId: keys.workspaceId,
-    resourceType: keys.resourceType,
-    resourceId: keys.resourceId,
-    version: keys.version,
-    resource: resourcePlain
-  };
-}
-var PUT_EVENTS_BATCH_SIZE = 10;
-var MAX_PUT_EVENTS_ROUNDS = 3;
-var eventBridgeClient;
-function getEventBridgeClient() {
-  const bus = process.env.DATA_EVENT_BUS_NAME?.trim();
-  if (!bus) {
-    return void 0;
-  }
-  if (!eventBridgeClient) {
-    eventBridgeClient = new EventBridgeClient({});
-  }
-  return eventBridgeClient;
-}
-var s3ClientForDlq;
-function getS3ClientForDlq() {
-  const bucket = process.env.DATA_STORE_PUT_EVENTS_DLQ_BUCKET?.trim();
-  if (!bucket) {
-    return void 0;
-  }
-  if (!s3ClientForDlq) {
-    s3ClientForDlq = new S3Client({});
-  }
-  return s3ClientForDlq;
-}
-async function writePutEventsFailuresToDlq(payload) {
-  const bucket = process.env.DATA_STORE_PUT_EVENTS_DLQ_BUCKET?.trim();
-  const client = getS3ClientForDlq();
-  if (!bucket || !client) {
-    throw new Error(
-      `PutEvents exhausted retries but DATA_STORE_PUT_EVENTS_DLQ_BUCKET is not set (${payload.reason})`
-    );
-  }
-  const day = payload.failedAt.slice(0, 10);
-  const key = `put-events-failed/${day}/${randomUUID()}.json`;
-  await client.send(
-    new PutObjectCommand({
-      Bucket: bucket,
-      Key: key,
-      Body: JSON.stringify(payload),
-      ContentType: "application/json"
-    })
-  );
-}
-async function putEventsChunkWithRetriesAndDlq(client, entries) {
-  if (entries.length === 0) {
-    return;
-  }
-  let pending = [...entries];
-  for (let round = 1; round <= MAX_PUT_EVENTS_ROUNDS; round++) {
-    try {
-      const out = await client.send(new PutEventsCommand({ Entries: pending }));
-      const failed = out.FailedEntryCount ?? 0;
-      if (failed === 0) {
-        return;
-      }
-      const nextPending = [];
-      out.Entries?.forEach((e, i) => {
-        if (e?.ErrorCode && pending[i]) {
-          nextPending.push(pending[i]);
-        }
-      });
-      pending = nextPending;
-      if (pending.length === 0) {
-        return;
-      }
-      if (round === MAX_PUT_EVENTS_ROUNDS) {
-        await writePutEventsFailuresToDlq({
-          dlqSchemaVersion: 1,
-          failedAt: (/* @__PURE__ */ new Date()).toISOString(),
-          reason: "put_events_partial_failure",
-          attemptRounds: MAX_PUT_EVENTS_ROUNDS,
-          entries: pending,
-          putEventsResultEntries: out.Entries
-        });
-        return;
-      }
-    } catch (sdkErr) {
-      const sdkMessage = sdkErr instanceof Error ? sdkErr.message : String(sdkErr);
-      if (round === MAX_PUT_EVENTS_ROUNDS) {
-        await writePutEventsFailuresToDlq({
-          dlqSchemaVersion: 1,
-          failedAt: (/* @__PURE__ */ new Date()).toISOString(),
-          reason: "put_events_sdk_error",
-          attemptRounds: MAX_PUT_EVENTS_ROUNDS,
-          entries: pending,
-          sdkError: sdkMessage
-        });
-        return;
-      }
-      await new Promise((r) => setTimeout(r, 50 * round));
-    }
-  }
-}
-async function publishDataStoreChangeEvents(pending) {
-  const client = getEventBridgeClient();
-  const busName = process.env.DATA_EVENT_BUS_NAME?.trim();
-  if (!client || !busName || pending.length === 0) {
-    return;
-  }
-  const entries = [];
-  for (const { change, keys } of pending) {
-    const detailObj = buildFhirCurrentResourceChangeDetail(change, keys);
-    const detail = JSON.stringify(detailObj);
-    const detailBytes = Buffer.byteLength(detail, "utf8");
-    if (detailBytes > DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES) {
-      throw new Error(
-        `Event detail is ${detailBytes} bytes (max ${DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES}); oversize strategy deferred per ADR 2026-03-02-01 (${keys.resourceType}/${keys.resourceId}).`
-      );
-    }
-    entries.push({
-      Source: DATA_STORE_CHANGE_EVENT_SOURCE,
-      DetailType: DATA_STORE_CHANGE_DETAIL_TYPE,
-      Detail: detail,
-      EventBusName: busName
-    });
-  }
-  for (let i = 0; i < entries.length; i += PUT_EVENTS_BATCH_SIZE) {
-    const chunk = entries.slice(i, i + PUT_EVENTS_BATCH_SIZE);
-    await putEventsChunkWithRetriesAndDlq(client, chunk);
-  }
-}
-async function handler(event) {
-  const records = [];
-  const archiveLambdaRegion = process.env.AWS_REGION ?? "";
-  const pendingPublish = [];
-  for (const rec of event.records) {
-    try {
-      const payload = Buffer.from(rec.data, "base64").toString("utf8");
-      const change = JSON.parse(payload);
-      if (shouldDropAsGlobalTableReplicationRecord(change, archiveLambdaRegion)) {
-        records.push({
-          recordId: rec.recordId,
-          result: "Dropped",
-          data: rec.data
-        });
-        continue;
-      }
-      const keys = parseCurrentResourceKeys(change);
-      if (!keys) {
-        records.push({
-          recordId: rec.recordId,
-          result: "Dropped",
-          data: rec.data
-        });
-        continue;
-      }
-      const archive = buildArchivePayload(change, keys);
-      const out = Buffer.from(`${JSON.stringify(archive)}
-`).toString(
-        "base64"
-      );
-      pendingPublish.push({ change, keys });
-      records.push({
-        recordId: rec.recordId,
-        result: "Ok",
-        data: out,
-        metadata: {
-          partitionKeys: {
-            tenantId: partitionToken(keys.tenantId),
-            workspaceId: partitionToken(keys.workspaceId),
-            resourceType: partitionToken(keys.resourceType),
-            resourceId: partitionToken(keys.resourceId),
-            version: partitionToken(keys.version)
-          }
-        }
-      });
-    } catch {
-      records.push({
-        recordId: rec.recordId,
-        result: "ProcessingFailed",
-        data: rec.data
-      });
-    }
-  }
-  await publishDataStoreChangeEvents(pendingPublish);
-  return { records };
-}
 export {
   handler,
   parseCurrentResourceKeys,

package/lib/firehose-archive-transform.handler.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/components/dynamodb/firehose-archive-transform.handler.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { AttributeValue } from \"@aws-sdk/client-dynamodb\";\nimport {\n  EventBridgeClient,\n  PutEventsCommand,\n  type PutEventsRequestEntry,\n  type PutEventsResultEntry,\n} from \"@aws-sdk/client-eventbridge\";\nimport { PutObjectCommand, S3Client } from \"@aws-sdk/client-s3\";\nimport type {\n  FirehoseTransformationEvent,\n  FirehoseTransformationResult,\n  FirehoseTransformationResultRecord,\n} from \"aws-lambda\";\nimport {\n  DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES,\n  DATA_STORE_CHANGE_DETAIL_TYPE,\n  DATA_STORE_CHANGE_EVENT_SOURCE,\n  buildFhirCurrentResourceChangeDetail,\n} from \"./data-store-change-events\";\nimport {\n  type DynamoDbStreamKinesisRecord,\n  dynamodbImageToPlain,\n} from \"./dynamodb-stream-record\";\n\nexport type { DynamoDbStreamKinesisRecord } from \"./dynamodb-stream-record\";\n\n/**\n * Firehose data-transformation handler: filters DynamoDB change records to\n * current FHIR resource items (SK = CURRENT, TID#…#WID#…#RT#…#ID#… PK),\n * writes archive JSON to S3 via Firehose, sets dynamic partition keys per\n * ADR 2026-03-11-02, and publishes de-identified change notifications to the\n * data event bus via PutEvents per ADR 2026-03-02-01, with retries and an S3\n * dead-letter bucket for entries that still fail.\n */\n\nconst CURRENT_SK = \"CURRENT\";\nconst PK_PATTERN =\n  /^TID#(?<tenantId>[^#]+)#WID#(?<workspaceId>[^#]+)#RT#(?<resourceType>[^#]+)#ID#(?<resourceId>.+)$/;\n\n/** DynamoDB-managed attribute on global table items (see AWS Global Tables legacy / replication docs). */\nconst AWS_REP_UPDATE_REGION = \"aws:rep:updateregion\";\n\nfunction getDynamoDbStringAttr(\n  image: Record<string, AttributeValue> | undefined,\n  name: string,\n): string | undefined {\n  if (!image) {\n    return undefined;\n  }\n  const av = image[name];\n  if (typeof av?.S === \"string\" && av.S.trim() !== \"\") {\n    return av.S.trim();\n  }\n  return undefined;\n}\n\nfunction primaryImageForReplicationCheck(\n  record: DynamoDbStreamKinesisRecord,\n): Record<string, AttributeValue> | undefined {\n  if (record.eventName === \"REMOVE\") {\n    return record.dynamodb?.OldImage;\n  }\n  return record.dynamodb?.NewImage;\n}\n\n/**\n * Returns true when this stream/Kinesis record should not be archived because it\n * represents a **replica-side application** of a global-table change (the logical\n * write originated in another Region).\n *\n * - If `aws:rep:updateregion` is present on the item image and differs from\n *   `archiveLambdaRegion`, the change was replicated into this Region (archive\n *   only in the Region that matches `aws:rep:updateregion`).\n * - Otherwise, if `userIdentity` matches the DynamoDB replication service SLR,\n *   treat as replication. **Excluded:** TTL deletes (`type` Service and\n *   `principalId` `dynamodb.amazonaws.com`) per AWS stream Identity docs.\n *\n * For MREC global tables version 2019.11.21, AWS documents that stream records\n * may not carry distinguishable metadata; the recommended approach is a custom\n * “write region” attribute on items. If neither that attribute nor\n * `aws:rep:updateregion` nor replication `userIdentity` applies, this function\n * returns false (no drop)—duplicate archives are possible if identical pipelines\n * run in every Region without those signals.\n */\nexport function shouldDropAsGlobalTableReplicationRecord(\n  record: DynamoDbStreamKinesisRecord,\n  archiveLambdaRegion: string,\n): boolean {\n  const image = primaryImageForReplicationCheck(record);\n  const updateRegion = getDynamoDbStringAttr(image, AWS_REP_UPDATE_REGION);\n  if (\n    updateRegion &&\n    archiveLambdaRegion &&\n    updateRegion !== archiveLambdaRegion\n  ) {\n    return true;\n  }\n\n  return isDynamoDbReplicationUserIdentity(record.userIdentity);\n}\n\nfunction isDynamoDbReplicationUserIdentity(userIdentity: unknown): boolean {\n  if (!userIdentity || typeof userIdentity !== \"object\") {\n    return false;\n  }\n  const ui = userIdentity as Record<string, unknown>;\n  const principalRaw = ui.principalId ?? ui.PrincipalId;\n  const typeRaw = ui.type ?? ui.Type;\n  const principal =\n    typeof principalRaw === \"string\" ? principalRaw.toLowerCase() : \"\";\n  const type = typeof typeRaw === \"string\" ? typeRaw.toLowerCase() : \"\";\n\n  if (type === \"service\" && principal === \"dynamodb.amazonaws.com\") {\n    return false;\n  }\n\n  const replicationMarkers = [\n    \"awsservicerolefordynamodbreplication\",\n    \"replication.dynamodb.amazonaws.com\",\n  ];\n  return replicationMarkers.some((m) => principal.includes(m));\n}\n\nexport function parseCurrentResourceKeys(record: DynamoDbStreamKinesisRecord): {\n  tenantId: string;\n  workspaceId: string;\n  resourceType: string;\n  resourceId: string;\n  version: string;\n} | null {\n  const keys = record.dynamodb?.Keys;\n  if (!keys) {\n    return null;\n  }\n  const pkAttr = keys.PK?.S;\n  const skAttr = keys.SK?.S;\n  if (!pkAttr || skAttr !== CURRENT_SK) {\n    return null;\n  }\n  const m = PK_PATTERN.exec(pkAttr);\n  if (!m?.groups) {\n    return null;\n  }\n  const { tenantId, workspaceId, resourceType, resourceId } = m.groups;\n  const image =\n    record.eventName === \"REMOVE\"\n      ? record.dynamodb?.OldImage\n      : record.dynamodb?.NewImage;\n  if (!image) {\n    return null;\n  }\n  const plain = dynamodbImageToPlain(image as Record<string, AttributeValue>);\n  const version = typeof plain.vid === \"string\" ? plain.vid : null;\n  if (!version) {\n    return null;\n  }\n  return { tenantId, workspaceId, resourceType, resourceId, version };\n}\n\nfunction partitionToken(value: string): string {\n  if (!value || value.trim() === \"\") {\n    return \"-\";\n  }\n  return value.replace(/[/\\\\]/g, \"_\");\n}\n\nfunction buildArchivePayload(\n  record: DynamoDbStreamKinesisRecord,\n  keys: ReturnType<typeof parseCurrentResourceKeys>,\n): Record<string, unknown> {\n  const newImage = record.dynamodb?.NewImage;\n  const oldImage = record.dynamodb?.OldImage;\n  const resourceImage = record.eventName === \"REMOVE\" ? oldImage : newImage;\n  const resourcePlain = resourceImage\n    ? dynamodbImageToPlain(resourceImage as Record<string, AttributeValue>)\n    : {};\n\n  if (typeof resourcePlain.resource === \"string\") {\n    try {\n      resourcePlain.resource = JSON.parse(resourcePlain.resource) as unknown;\n    } catch {\n      /* keep raw string if not valid JSON */\n    }\n  }\n\n  return {\n    eventName: record.eventName,\n    archivedAt: new Date().toISOString(),\n    tenantId: keys!.tenantId,\n    workspaceId: keys!.workspaceId,\n    resourceType: keys!.resourceType,\n    resourceId: keys!.resourceId,\n    version: keys!.version,\n    resource: resourcePlain,\n  };\n}\n\nconst PUT_EVENTS_BATCH_SIZE = 10;\n\n/** Full PutEvents rounds per chunk (initial attempt + failure-driven retries). */\nconst MAX_PUT_EVENTS_ROUNDS = 3;\n\nlet eventBridgeClient: EventBridgeClient | undefined;\n\nfunction getEventBridgeClient(): EventBridgeClient | undefined {\n  const bus = process.env.DATA_EVENT_BUS_NAME?.trim();\n  if (!bus) {\n    return undefined;\n  }\n  if (!eventBridgeClient) {\n    eventBridgeClient = new EventBridgeClient({});\n  }\n  return eventBridgeClient;\n}\n\nlet s3ClientForDlq: S3Client | undefined;\n\nfunction getS3ClientForDlq(): S3Client | undefined {\n  const bucket = process.env.DATA_STORE_PUT_EVENTS_DLQ_BUCKET?.trim();\n  if (!bucket) {\n    return undefined;\n  }\n  if (!s3ClientForDlq) {\n    s3ClientForDlq = new S3Client({});\n  }\n  return s3ClientForDlq;\n}\n\ntype PutEventsEntry = PutEventsRequestEntry;\n\ninterface PutEventsDlqPayload {\n  dlqSchemaVersion: 1;\n  failedAt: string;\n  reason: \"put_events_partial_failure\" | \"put_events_sdk_error\";\n  attemptRounds: number;\n  entries: PutEventsEntry[];\n  putEventsResultEntries?: PutEventsResultEntry[];\n  sdkError?: string;\n}\n\nasync function writePutEventsFailuresToDlq(\n  payload: PutEventsDlqPayload,\n): Promise<void> {\n  const bucket = process.env.DATA_STORE_PUT_EVENTS_DLQ_BUCKET?.trim();\n  const client = getS3ClientForDlq();\n  if (!bucket || !client) {\n    throw new Error(\n      `PutEvents exhausted retries but DATA_STORE_PUT_EVENTS_DLQ_BUCKET is not set (${payload.reason})`,\n    );\n  }\n  const day = payload.failedAt.slice(0, 10);\n  const key = `put-events-failed/${day}/${randomUUID()}.json`;\n  await client.send(\n    new PutObjectCommand({\n      Bucket: bucket,\n      Key: key,\n      Body: JSON.stringify(payload),\n      ContentType: \"application/json\",\n    }),\n  );\n}\n\n/**\n * Sends one PutEvents batch (≤10 entries) with up to {@link MAX_PUT_EVENTS_ROUNDS}\n * rounds. After the last round, remaining failures or a final SDK error are\n * written to the DLQ S3 bucket (if configured); DLQ write failure throws.\n */\nasync function putEventsChunkWithRetriesAndDlq(\n  client: EventBridgeClient,\n  entries: PutEventsEntry[],\n): Promise<void> {\n  if (entries.length === 0) {\n    return;\n  }\n\n  let pending = [...entries];\n\n  for (let round = 1; round <= MAX_PUT_EVENTS_ROUNDS; round++) {\n    try {\n      const out = await client.send(new PutEventsCommand({ Entries: pending }));\n      const failed = out.FailedEntryCount ?? 0;\n      if (failed === 0) {\n        return;\n      }\n\n      const nextPending: PutEventsEntry[] = [];\n      out.Entries?.forEach((e: PutEventsResultEntry | undefined, i: number) => {\n        if (e?.ErrorCode && pending[i]) {\n          nextPending.push(pending[i]!);\n        }\n      });\n      pending = nextPending;\n\n      if (pending.length === 0) {\n        return;\n      }\n\n      if (round === MAX_PUT_EVENTS_ROUNDS) {\n        await writePutEventsFailuresToDlq({\n          dlqSchemaVersion: 1,\n          failedAt: new Date().toISOString(),\n          reason: \"put_events_partial_failure\",\n          attemptRounds: MAX_PUT_EVENTS_ROUNDS,\n          entries: pending,\n          putEventsResultEntries: out.Entries,\n        });\n        return;\n      }\n    } catch (sdkErr) {\n      const sdkMessage =\n        sdkErr instanceof Error ? sdkErr.message : String(sdkErr);\n      if (round === MAX_PUT_EVENTS_ROUNDS) {\n        await writePutEventsFailuresToDlq({\n          dlqSchemaVersion: 1,\n          failedAt: new Date().toISOString(),\n          reason: \"put_events_sdk_error\",\n          attemptRounds: MAX_PUT_EVENTS_ROUNDS,\n          entries: pending,\n          sdkError: sdkMessage,\n        });\n        return;\n      }\n      await new Promise((r) => setTimeout(r, 50 * round));\n    }\n  }\n}\n\nasync function publishDataStoreChangeEvents(\n  pending: Array<{\n    change: DynamoDbStreamKinesisRecord;\n    keys: NonNullable<ReturnType<typeof parseCurrentResourceKeys>>;\n  }>,\n): Promise<void> {\n  const client = getEventBridgeClient();\n  const busName = process.env.DATA_EVENT_BUS_NAME?.trim();\n  if (!client || !busName || pending.length === 0) {\n    return;\n  }\n\n  const entries: PutEventsEntry[] = [];\n  for (const { change, keys } of pending) {\n    const detailObj = buildFhirCurrentResourceChangeDetail(change, keys);\n    const detail = JSON.stringify(detailObj);\n    const detailBytes = Buffer.byteLength(detail, \"utf8\");\n    if (detailBytes > DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES) {\n      throw new Error(\n        `Event detail is ${detailBytes} bytes (max ${DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES}); ` +\n          `oversize strategy deferred per ADR 2026-03-02-01 (${keys.resourceType}/${keys.resourceId}).`,\n      );\n    }\n    entries.push({\n      Source: DATA_STORE_CHANGE_EVENT_SOURCE,\n      DetailType: DATA_STORE_CHANGE_DETAIL_TYPE,\n      Detail: detail,\n      EventBusName: busName,\n    });\n  }\n\n  for (let i = 0; i < entries.length; i += PUT_EVENTS_BATCH_SIZE) {\n    const chunk = entries.slice(i, i + PUT_EVENTS_BATCH_SIZE);\n    await putEventsChunkWithRetriesAndDlq(client, chunk);\n  }\n}\n\nexport async function handler(\n  event: FirehoseTransformationEvent,\n): Promise<FirehoseTransformationResult> {\n  const records: FirehoseTransformationResultRecord[] = [];\n  const archiveLambdaRegion = process.env.AWS_REGION ?? \"\";\n  const pendingPublish: Array<{\n    change: DynamoDbStreamKinesisRecord;\n    keys: NonNullable<ReturnType<typeof parseCurrentResourceKeys>>;\n  }> = [];\n\n  for (const rec of event.records) {\n    try {\n      const payload = Buffer.from(rec.data, \"base64\").toString(\"utf8\");\n      const change = JSON.parse(payload) as DynamoDbStreamKinesisRecord;\n\n      if (\n        shouldDropAsGlobalTableReplicationRecord(change, archiveLambdaRegion)\n      ) {\n        records.push({\n          recordId: rec.recordId,\n          result: \"Dropped\",\n          data: rec.data,\n        });\n        continue;\n      }\n\n      const keys = parseCurrentResourceKeys(change);\n\n      if (!keys) {\n        records.push({\n          recordId: rec.recordId,\n          result: \"Dropped\",\n          data: rec.data,\n        });\n        continue;\n      }\n\n      const archive = buildArchivePayload(change, keys);\n      const out = Buffer.from(`${JSON.stringify(archive)}\\n`).toString(\n        \"base64\",\n      );\n\n      pendingPublish.push({ change, keys });\n\n      records.push({\n        recordId: rec.recordId,\n        result: \"Ok\",\n        data: out,\n        metadata: {\n          partitionKeys: {\n            tenantId: partitionToken(keys.tenantId),\n            workspaceId: partitionToken(keys.workspaceId),\n            resourceType: partitionToken(keys.resourceType),\n            resourceId: partitionToken(keys.resourceId),\n            version: partitionToken(keys.version),\n          },\n        },\n      });\n    } catch {\n      records.push({\n        recordId: rec.recordId,\n        result: \"ProcessingFailed\",\n        data: rec.data,\n      });\n    }\n  }\n\n  await publishDataStoreChangeEvents(pendingPublish);\n\n  return { records };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/lib/index.d.mts

@@ -4,7 +4,7 @@ import { IConstruct, Construct } from 'constructs';
 import { Certificate, CertificateProps, ICertificate } from 'aws-cdk-lib/aws-certificatemanager';
 import { HttpApiProps, HttpApi, IHttpApi, DomainName } from 'aws-cdk-lib/aws-apigatewayv2';
 import { GraphqlApi, IGraphqlApi, GraphqlApiProps } from 'aws-cdk-lib/aws-appsync';
-import { UserPool, UserPoolProps, UserPoolClient, UserPoolClientProps, UserPoolDomain, UserPoolDomainProps, IUserPool, IUserPoolClient, IUserPoolDomain } from 'aws-cdk-lib/aws-cognito';
+import { UserPoolClient, UserPoolClientProps, IUserPool, UserPool, UserPoolProps, UserPoolDomain, UserPoolDomainProps, IUserPoolClient, IUserPoolDomain } from 'aws-cdk-lib/aws-cognito';
 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';
@@ -15,6 +15,8 @@ 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 * 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';
@@ -387,6 +389,47 @@ declare class RootGraphqlApi extends GraphqlApi {
     constructor(scope: Construct, props?: Omit<RootGraphqlApiProps, "name">);
 }
 
+interface CognitoFixtureSeederClientProps extends Partial<Omit<UserPoolClientProps, "userPool" | "generateSecret">> {
+    readonly userPool: IUserPool;
+}
+/**
+ * Dedicated Cognito app client for the OpenHI fixture-seeder CLI
+ * (`@openhi/seed-fixtures`).
+ *
+ * Why a dedicated client (vs reusing the SPA client):
+ * - Tightly scoped: only the seeder consumes tokens issued here, so an
+ *   audit trail of seeder activity is cleanly separable.
+ * - Decoupled from the SPA client's OAuth flows — no risk of breaking
+ *   web-app sign-in by tweaking auth-flow settings here.
+ * - Stage-conditional creation upstream (only provisioned in non-prod
+ *   environments) means prod stacks never carry a code path that could
+ *   issue a fixture-seeder token in the first place.
+ *
+ * Why USER_PASSWORD_AUTH (vs M2M client-credentials):
+ * - Cognito's M2M tier has a per-app-client monthly fee plus per-token
+ *   activity charges. For sporadic non-prod fixture runs the per-client
+ *   fee dominates the bill, especially if every dev branch spins up
+ *   its own auth stack.
+ * - USER_PASSWORD_AUTH against a service `fixture-seeder` user keeps
+ *   the cost in MAU territory (free under the 50K MAU tier).
+ * - Tradeoff: passwords need rotation and the service user must be
+ *   provisioned per non-prod environment (manual or scripted post-deploy).
+ *
+ * No client secret (`generateSecret: false`): USER_PASSWORD_AUTH
+ * authenticates with the password directly; a secret would just add
+ * another credential to manage without strengthening anything.
+ */
+declare class CognitoFixtureSeederClient extends UserPoolClient {
+    /**
+     * SSM parameter name suffix used to publish this client's ID for
+     * cross-stack lookups. Built into a full parameter name via
+     * `buildParameterName` with `serviceType` AUTH (since the auth stack
+     * owns this resource).
+     */
+    static readonly SSM_PARAM_NAME = "COGNITO_FIXTURE_SEEDER_CLIENT";
+    constructor(scope: Construct, props: CognitoFixtureSeederClientProps);
+}
+
 /**
  * @see sites/www-docs/content/packages/@openhi/constructs/components/cognito/cognito-user-pool.md
  */
@@ -524,13 +567,25 @@ interface DynamoDbDataStoreProps extends Omit<TableProps, "tableName" | "removal
     readonly removalPolicy?: RemovalPolicy;
 }
 /**
- * DynamoDB table implementing the single-table design for app data (e.g. FHIR
- * resources and configuration).
+ * DynamoDB table implementing the single-table design for app data (FHIR
+ * resources data plane and platform control plane), per planning ADR-011 and
+ * DR-004.
  *
  * @see {@link https://github.com/codedrifters/openhi/blob/main/sites/www-docs/content/architecture/dynamodb-single-table-design.md | DynamoDB Single-Table Design}
  *
  * Primary key: PK (String), SK (String).
- * GSIs: GSI1 (reverse reference), GSI2 (identifier lookup), GSI3 (facility ops), GSI4 (resource type list).
+ *
+ * GSIs:
+ * - **GSI1 — Unified Sharded List** (`GSI1PK`/`GSI1SK`, INCLUDE projection per
+ *   DR-004). Primary list/lookup index for both data-plane FHIR resources and
+ *   control-plane entities (User, Tenant, Workspace, Membership, Role,
+ *   RoleAssignment, Configuration). PK shape:
+ *   `TID#<tid>#WID#<wid>#RT#<Type>#SHARD#<n>` with 4 shards
+ *   (`n = hash(id) mod 4`). SK shape per `extractSortKey`: labeled types use
+ *   `<normalizedLabel>#<id>`; unlabeled use `<ISO-8601 lastUpdated>#<id>`.
+ * - **GSI2 — Sub-Lookup** (`GSI2PK`/`GSI2SK`, INCLUDE projection). Resolves
+ *   `UserEntity` from a Cognito `sub` for the Pre Token Generation Lambda.
+ *   PK shape: `USER#SUB#<cognitoSub>`. SK shape: `CURRENT`.
  *
  * For historical archive to S3, pass `kinesisStream` and `stream` (e.g.
  * `StreamViewType.NEW_AND_OLD_IMAGES`) on the table props per ADR 2026-03-11-02.
@@ -569,6 +624,111 @@ declare class OpsEventBus extends EventBus {
     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
+ * cross-stack reference. The schema name is intentionally NOT published — it
+ * is a deterministic function of `branchHash` and consumers compute it locally
+ * via {@link getPostgresReplicaSchemaName}.
+ */
+declare const POSTGRES_REPLICA_CLUSTER_ARN_SSM_NAME = "POSTGRES_REPLICA_CLUSTER_ARN";
+declare const POSTGRES_REPLICA_SECRET_ARN_SSM_NAME = "POSTGRES_REPLICA_SECRET_ARN";
+declare const POSTGRES_REPLICA_DATABASE_NAME_SSM_NAME = "POSTGRES_REPLICA_DATABASE_NAME";
+/**
+ * Derive the per-branch Postgres schema name from a branch hash. The `b_`
+ * prefix guarantees a leading letter (Postgres identifier rule). Branch hashes
+ * are 6 hex chars from {@link OpenHiService.branchHash} so the resulting
+ * `b_xxxxxx` is well within the 63-byte identifier limit.
+ */
+declare function getPostgresReplicaSchemaName(branchHash: string): string;
+interface DataStorePostgresReplicaProps {
+    /**
+     * Kinesis stream that receives DynamoDB item-level changes (the same stream
+     * that backs {@link DataStoreHistoricalArchive}). The replication Lambda is
+     * registered as a parallel consumer.
+     */
+    readonly kinesisStream: kinesis.IStream;
+    /**
+     * Removal policy for the cluster, secret, and dependent resources.
+     */
+    readonly removalPolicy: RemovalPolicy;
+    /**
+     * Short hash unique to the stack — used in the cluster identifier.
+     */
+    readonly stackHash: string;
+    /**
+     * Short hash unique to the branch — used to derive the per-branch schema
+     * name (`b_<branchHash>`) inside the Postgres database.
+     */
+    readonly branchHash: string;
+    /**
+     * Optional VPC override. If absent, the construct creates a minimal isolated
+     * VPC (2 AZs, no NAT gateways) just for the cluster and replication Lambda.
+     */
+    readonly vpc?: ec2.IVpc;
+    /**
+     * Optional database name override.
+     * @default "openhi"
+     */
+    readonly databaseName?: string;
+    /**
+     * Aurora Serverless v2 minimum capacity in ACUs. Defaults to 1 so the
+     * writer stays warm — avoids the ~10–20s scale-up wait that a cold
+     * (0 ACU) cluster imposes on the next request. Set explicitly to 0 to
+     * opt back into scale-to-zero if idle cost becomes the dominant concern.
+     */
+    readonly minCapacity?: number;
+    /**
+     * Aurora Serverless v2 maximum capacity in ACUs. Defaults to 2 — adequate
+     * for the PoC's replication-only workload.
+     */
+    readonly maxCapacity?: number;
+}
+/**
+ * DynamoDB change stream → Postgres replication tier (ADR 2026-04-17-01,
+ * phase 1). Provisions an Aurora Serverless v2 PostgreSQL cluster and a
+ * Lambda consumer on the existing change-stream that projects each current
+ * FHIR resource into a JSONB `resources` table under a per-branch schema.
+ *
+ * Phase 1 is replication-only; query routing and SearchParameter-specific
+ * indexes are intentionally deferred. Per-branch *clusters* (rather than the
+ * shared cluster suggested by the ADR) are an explicit PoC simplification —
+ * see the ADR's "Operational notes" section for the long-term direction.
+ *
+ * @see sites/www-docs/content/architecture/adr/2026-04-17-01-ad-hoc-query-support-fhir-api.md
+ */
+declare class DataStorePostgresReplica extends Construct {
+    /**
+     * Resolve the cluster ARN published by an upstream {@link DataStorePostgresReplica}.
+     * Use from any stack that needs to grant `rds-data:ExecuteStatement` against
+     * the cluster.
+     */
+    static clusterArnFromConstruct(scope: Construct): string;
+    /**
+     * Resolve the credentials secret ARN published by an upstream
+     * {@link DataStorePostgresReplica}. Use from any stack that needs to grant
+     * `secretsmanager:GetSecretValue` against the secret.
+     */
+    static secretArnFromConstruct(scope: Construct): string;
+    /**
+     * Resolve the database name published by an upstream
+     * {@link DataStorePostgresReplica}.
+     */
+    static databaseNameFromConstruct(scope: Construct): string;
+    readonly vpc: ec2.IVpc;
+    readonly cluster: rds.DatabaseCluster;
+    readonly replicationFunction: NodejsFunction;
+    readonly databaseName: string;
+    readonly schemaName: string;
+    constructor(scope: Construct, id: string, props: DataStorePostgresReplicaProps);
+    /**
+     * Publishes the cluster ARN, secret ARN, and database name as discoverable
+     * SSM parameters so the REST API stack (and any future read-side consumer)
+     * can wire RDS Data API access without a direct CDK cross-stack reference.
+     */
+    private publishCoordinatesToSsm;
+}
+
 /**
  * @see sites/www-docs/content/packages/@openhi/constructs/components/route-53/child-hosted-zone.md
  */
@@ -747,6 +907,17 @@ declare class OpenHiAuthService extends OpenHiService {
      * Returns an IUserPoolClient by looking up the Auth stack's User Pool Client ID from SSM.
      */
     static userPoolClientFromConstruct(scope: Construct): IUserPoolClient;
+    /**
+     * Returns the dedicated fixture-seeder IUserPoolClient by looking up
+     * its ID from SSM. Only non-prod auth stacks publish this parameter
+     * (per the conditional in {@link createFixtureSeederClient}); calling
+     * this against a prod-deployed stack will fail at lookup time.
+     *
+     * Consumed by `OpenHiRestApiService` (in non-prod) so the authorizer
+     * accepts tokens issued by this client, and by the seed-fixtures CLI
+     * to drive USER_PASSWORD_AUTH against this client's ID.
+     */
+    static fixtureSeederClientFromConstruct(scope: Construct): IUserPoolClient;
     /**
      * Returns an IUserPoolDomain by looking up the Auth stack's User Pool Domain from SSM.
      */
@@ -763,6 +934,12 @@ declare class OpenHiAuthService extends OpenHiService {
     readonly userPool: IUserPool;
     readonly userPoolClient: IUserPoolClient;
     readonly userPoolDomain: IUserPoolDomain;
+    /**
+     * Dedicated USER_PASSWORD_AUTH client for the seed-fixtures CLI.
+     * Only created in non-prod environments (see
+     * {@link createFixtureSeederClient}). `undefined` in prod.
+     */
+    readonly fixtureSeederClient?: IUserPoolClient;
     constructor(ohEnv: OpenHiEnvironment, props?: OpenHiAuthServiceProps);
     /**
      * Creates the KMS key for the Cognito User Pool and exports its ARN to SSM.
@@ -787,6 +964,18 @@ declare class OpenHiAuthService extends OpenHiService {
      * Override to customize.
      */
     protected createUserPoolClient(): IUserPoolClient;
+    /**
+     * Creates the dedicated USER_PASSWORD_AUTH app client for the
+     * `@openhi/seed-fixtures` CLI, **only** in non-prod environments.
+     * Returns `undefined` when this stack is being deployed to a prod
+     * stage so the prod auth stack carries no fixture-seeder code path.
+     *
+     * Operator post-deploy: create a `fixture-seeder` Cognito user with
+     * a service password (manually via console or scripted with
+     * `aws cognito-idp admin-create-user`); the CLI consumes those creds
+     * via env vars to drive `InitiateAuth`.
+     */
+    protected createFixtureSeederClient(): IUserPoolClient | undefined;
     /**
      * Creates the User Pool Domain (Cognito hosted UI) and exports domain name to SSM.
      * Look up via {@link OpenHiAuthService.userPoolDomainFromConstruct}.
@@ -983,6 +1172,13 @@ declare class OpenHiDataService extends OpenHiService {
      * notifications for current FHIR resources (ADRs 2026-03-11-02, 2026-03-02-01).
      */
     readonly dataStoreHistoricalArchive: DataStoreHistoricalArchive;
+    /**
+     * Postgres replication tier (ADR 2026-04-17-01, phase 1). A second consumer
+     * on the change stream that projects current FHIR resources into a JSONB
+     * `resources` table on Aurora Serverless v2. Phase 1 is replication-only;
+     * the read path is not wired up yet.
+     */
+    readonly dataStorePostgresReplica: DataStorePostgresReplica;
     constructor(ohEnv: OpenHiEnvironment, props?: OpenHiDataServiceProps);
     /**
      * Creates the data event bus.
@@ -1023,4 +1219,4 @@ declare class OpenHiGraphqlService extends OpenHiService {
     protected createRootGraphqlApi(): RootGraphqlApi;
 }
 
-export { type BuildParameterNameProps, ChildHostedZone, type ChildHostedZoneProps, 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, 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, PreTokenGenerationLambda, REST_API_BASE_URL_SSM_NAME, RootGraphqlApi, type RootGraphqlApiProps, RootHostedZone, RootHttpApi, type RootHttpApiProps, RootWildcardCertificate, STATIC_HOSTING_SERVICE_TYPE, StaticHosting, type StaticHostingProps, buildFhirCurrentResourceChangeDetail, getDynamoDbDataStoreTableName };
+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, PreTokenGenerationLambda, REST_API_BASE_URL_SSM_NAME, RootGraphqlApi, type RootGraphqlApiProps, RootHostedZone, RootHttpApi, type RootHttpApiProps, RootWildcardCertificate, STATIC_HOSTING_SERVICE_TYPE, StaticHosting, type StaticHostingProps, buildFhirCurrentResourceChangeDetail, getDynamoDbDataStoreTableName, getPostgresReplicaSchemaName };