@openhi/constructs 0.0.159 → 0.0.161

package/lib/counter-maintenance.handler.mjs

@@ -0,0 +1,180 @@
+import {
+  COUNTER_TARGET,
+  applyCounterDeltaOperation,
+  isAdminRoleAssignment
+} from "./chunk-RQKJNMX5.mjs";
+import {
+  COUNTER_MAINTENANCE_CONSUMER_NAME,
+  import_workflows
+} from "./chunk-LKKLO66E.mjs";
+import "./chunk-EUIP2U5F.mjs";
+import "./chunk-TRY7JGWO.mjs";
+import {
+  require_lib
+} from "./chunk-KMEWULMX.mjs";
+import {
+  __toESM
+} from "./chunk-LZOMFHX3.mjs";
+
+// src/workflows/control-plane/counter-maintenance/counter-maintenance.handler.ts
+var import_workflows2 = __toESM(require_lib());
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+
+// src/data/operations/control/counters/counter-event-router.ts
+function membershipMutations(payload, delta) {
+  const mutations = [];
+  if (payload.workspaceId !== void 0) {
+    mutations.push({
+      target: COUNTER_TARGET.Workspace,
+      tenantId: payload.tenantId,
+      workspaceId: payload.workspaceId,
+      attribute: "usersInWorkspace",
+      delta
+    });
+    if (payload.userId !== void 0) {
+      mutations.push({
+        target: COUNTER_TARGET.User,
+        userId: payload.userId,
+        attribute: "workspacesForUser",
+        delta
+      });
+    }
+    return mutations;
+  }
+  mutations.push({
+    target: COUNTER_TARGET.Tenant,
+    tenantId: payload.tenantId,
+    attribute: "usersInTenant",
+    delta
+  });
+  if (payload.userId !== void 0) {
+    mutations.push({
+      target: COUNTER_TARGET.User,
+      userId: payload.userId,
+      attribute: "tenantsForUser",
+      delta
+    });
+  }
+  return mutations;
+}
+function roleAssignmentMutations(payload, delta) {
+  if (payload.workspaceId === void 0) {
+    return [];
+  }
+  const attribute = isAdminRoleAssignment({
+    roleLevel: payload.roleLevel,
+    roleId: payload.roleId
+  }) ? "adminUsersInWorkspace" : "normalUsersInWorkspace";
+  return [
+    {
+      target: COUNTER_TARGET.Workspace,
+      tenantId: payload.tenantId,
+      workspaceId: payload.workspaceId,
+      attribute,
+      delta
+    }
+  ];
+}
+function workspaceMutations(payload, delta) {
+  return [
+    {
+      target: COUNTER_TARGET.Tenant,
+      tenantId: payload.tenantId,
+      attribute: "workspacesInTenant",
+      delta
+    }
+  ];
+}
+
+// src/workflows/control-plane/counter-maintenance/counter-maintenance.handler.ts
+var errorMessage = (err) => err instanceof Error ? err.message : String(err);
+function resolveEvent(event) {
+  const detailType = event["detail-type"];
+  switch (detailType) {
+    case import_workflows.ControlPlaneMembershipCreatedV1.detailType:
+      return resolveMembership(event, import_workflows.ControlPlaneMembershipCreatedV1, 1);
+    case import_workflows.ControlPlaneMembershipDeletedV1.detailType:
+      return resolveMembership(event, import_workflows.ControlPlaneMembershipDeletedV1, -1);
+    case import_workflows.ControlPlaneRoleAssignmentCreatedV1.detailType:
+      return resolveRoleAssignment(
+        event,
+        import_workflows.ControlPlaneRoleAssignmentCreatedV1,
+        1
+      );
+    case import_workflows.ControlPlaneRoleAssignmentDeletedV1.detailType:
+      return resolveRoleAssignment(
+        event,
+        import_workflows.ControlPlaneRoleAssignmentDeletedV1,
+        -1
+      );
+    case import_workflows.ControlPlaneWorkspaceCreatedV1.detailType:
+      return resolveWorkspace(event, import_workflows.ControlPlaneWorkspaceCreatedV1, 1);
+    case import_workflows.ControlPlaneWorkspaceDeletedV1.detailType:
+      return resolveWorkspace(event, import_workflows.ControlPlaneWorkspaceDeletedV1, -1);
+    default:
+      return null;
+  }
+}
+function resolveMembership(event, entry, delta) {
+  const parsed = (0, import_workflows2.parseWorkflowEvent)(event, entry);
+  return {
+    mutations: membershipMutations(parsed.envelope.payload, delta),
+    dedupKey: parsed.dedupKey
+  };
+}
+function resolveRoleAssignment(event, entry, delta) {
+  const parsed = (0, import_workflows2.parseWorkflowEvent)(event, entry);
+  return {
+    mutations: roleAssignmentMutations(parsed.envelope.payload, delta),
+    dedupKey: parsed.dedupKey
+  };
+}
+function resolveWorkspace(event, entry, delta) {
+  const parsed = (0, import_workflows2.parseWorkflowEvent)(event, entry);
+  return {
+    mutations: workspaceMutations(parsed.envelope.payload, delta),
+    dedupKey: parsed.dedupKey
+  };
+}
+var runCounterMaintenance = async (event, deps) => {
+  const resolved = resolveEvent(event);
+  if (resolved === null) {
+    return;
+  }
+  const recordResult = await deps.dedupClient.recordIfAbsent({
+    consumerName: COUNTER_MAINTENANCE_CONSUMER_NAME,
+    eventId: resolved.dedupKey.eventId,
+    attempt: resolved.dedupKey.attempt
+  });
+  if (!recordResult.recorded) {
+    return;
+  }
+  try {
+    for (const mutation of resolved.mutations) {
+      await deps.applyMutation(mutation);
+    }
+  } catch (err) {
+    await deps.dedupClient.markFailed({
+      consumerName: COUNTER_MAINTENANCE_CONSUMER_NAME,
+      eventId: resolved.dedupKey.eventId,
+      attempt: resolved.dedupKey.attempt,
+      reason: errorMessage(err)
+    });
+    throw err;
+  }
+};
+var productionDependencies = () => {
+  const dynamodb = new DynamoDBClient({});
+  return {
+    dedupClient: (0, import_workflows2.workflowDedupClient)(dynamodb),
+    applyMutation: async (mutation) => {
+      await applyCounterDeltaOperation({ mutation });
+    }
+  };
+};
+var handler = async (event) => runCounterMaintenance(event, productionDependencies());
+export {
+  handler,
+  runCounterMaintenance
+};
+//# sourceMappingURL=counter-maintenance.handler.mjs.map

package/lib/counter-maintenance.handler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workflows/control-plane/counter-maintenance/counter-maintenance.handler.ts","../src/data/operations/control/counters/counter-event-router.ts"],"sourcesContent":["import { DynamoDBClient } from \"@aws-sdk/client-dynamodb\";\nimport {\n  parseWorkflowEvent,\n  workflowDedupClient,\n  type ControlPlaneMembershipChangedV1Detail,\n  type ControlPlaneRoleAssignmentChangedV1Detail,\n  type ControlPlaneWorkspaceChangedV1Detail,\n  type WorkflowDedupClient,\n  type WorkflowDetailTypeEntry,\n} from \"@openhi/workflows\";\nimport type { EventBridgeEvent } from \"aws-lambda\";\nimport {\n  COUNTER_MAINTENANCE_CONSUMER_NAME,\n  ControlPlaneMembershipCreatedV1,\n  ControlPlaneMembershipDeletedV1,\n  ControlPlaneRoleAssignmentCreatedV1,\n  ControlPlaneRoleAssignmentDeletedV1,\n  ControlPlaneWorkspaceCreatedV1,\n  ControlPlaneWorkspaceDeletedV1,\n} from \"./events\";\nimport { applyCounterDeltaOperation } from \"../../../data/operations/control/counters/counter-apply-operation\";\nimport {\n  type CounterMutation,\n  membershipMutations,\n  roleAssignmentMutations,\n  workspaceMutations,\n} from \"../../../data/operations/control/counters/counter-event-router\";\n\n/**\n * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/counter-maintenance/counter-maintenance-handler.md\n *\n * ADR-028 counter-maintenance consumer. Invoked once per control-plane\n * domain event on the control event bus. Dedupes the event on\n * `(consumerName, eventId, attempt)` via the TR-015 `WorkflowDedupTable`,\n * then applies the resolved atomic-ADD counter deltas to the affected\n * canonical Tenant / Workspace / User records.\n *\n * Idempotency: an atomic ADD is not idempotent, so a replayed event must\n * be a no-op. `recordIfAbsent` is the circuit-breaker — when it returns\n * `recorded: false` a prior delivery of this exact `(eventId, attempt)`\n * already applied the deltas, so the handler exits without re-applying.\n * The dedup write happens-before the counter mutations, exactly as\n * ADR-028 § Consume requires.\n */\n\ntype CounterMaintenanceEvent = EventBridgeEvent<string, unknown>;\n\nconst errorMessage = (err: unknown): string =>\n  err instanceof Error ? err.message : String(err);\n\n/**\n * Resolve the counter mutations for an event, selecting the matching\n * detail-type registry entry so `parseWorkflowEvent` validates the\n * envelope against the right source + detail-type and surfaces the\n * `(eventId, attempt)` dedup tuple.\n *\n * Returns `null` for a detail-type this consumer does not handle (the\n * EventBridge rule should never deliver one, but the guard keeps a\n * mis-targeted rule from throwing on an unknown shape).\n */\nfunction resolveEvent(event: CounterMaintenanceEvent): {\n  readonly mutations: Array<CounterMutation>;\n  readonly dedupKey: { readonly eventId: string; readonly attempt: number };\n} | null {\n  const detailType = event[\"detail-type\"];\n\n  switch (detailType) {\n    case ControlPlaneMembershipCreatedV1.detailType:\n      return resolveMembership(event, ControlPlaneMembershipCreatedV1, 1);\n    case ControlPlaneMembershipDeletedV1.detailType:\n      return resolveMembership(event, ControlPlaneMembershipDeletedV1, -1);\n    case ControlPlaneRoleAssignmentCreatedV1.detailType:\n      return resolveRoleAssignment(\n        event,\n        ControlPlaneRoleAssignmentCreatedV1,\n        1,\n      );\n    case ControlPlaneRoleAssignmentDeletedV1.detailType:\n      return resolveRoleAssignment(\n        event,\n        ControlPlaneRoleAssignmentDeletedV1,\n        -1,\n      );\n    case ControlPlaneWorkspaceCreatedV1.detailType:\n      return resolveWorkspace(event, ControlPlaneWorkspaceCreatedV1, 1);\n    case ControlPlaneWorkspaceDeletedV1.detailType:\n      return resolveWorkspace(event, ControlPlaneWorkspaceDeletedV1, -1);\n    default:\n      return null;\n  }\n}\n\nfunction resolveMembership(\n  event: CounterMaintenanceEvent,\n  entry: WorkflowDetailTypeEntry<ControlPlaneMembershipChangedV1Detail>,\n  delta: 1 | -1,\n): {\n  mutations: Array<CounterMutation>;\n  dedupKey: { eventId: string; attempt: number };\n} {\n  const parsed = parseWorkflowEvent(event, entry);\n  return {\n    mutations: membershipMutations(parsed.envelope.payload, delta),\n    dedupKey: parsed.dedupKey,\n  };\n}\n\nfunction resolveRoleAssignment(\n  event: CounterMaintenanceEvent,\n  entry: WorkflowDetailTypeEntry<ControlPlaneRoleAssignmentChangedV1Detail>,\n  delta: 1 | -1,\n): {\n  mutations: Array<CounterMutation>;\n  dedupKey: { eventId: string; attempt: number };\n} {\n  const parsed = parseWorkflowEvent(event, entry);\n  return {\n    mutations: roleAssignmentMutations(parsed.envelope.payload, delta),\n    dedupKey: parsed.dedupKey,\n  };\n}\n\nfunction resolveWorkspace(\n  event: CounterMaintenanceEvent,\n  entry: WorkflowDetailTypeEntry<ControlPlaneWorkspaceChangedV1Detail>,\n  delta: 1 | -1,\n): {\n  mutations: Array<CounterMutation>;\n  dedupKey: { eventId: string; attempt: number };\n} {\n  const parsed = parseWorkflowEvent(event, entry);\n  return {\n    mutations: workspaceMutations(parsed.envelope.payload, delta),\n    dedupKey: parsed.dedupKey,\n  };\n}\n\n/** Dependency seam for tests; production wires the real dedup client. */\nexport interface CounterMaintenanceDependencies {\n  readonly dedupClient: WorkflowDedupClient;\n  /**\n   * Apply one resolved counter mutation. Defaults to\n   * {@link applyCounterDeltaOperation}; tests inject a spy.\n   */\n  readonly applyMutation: (mutation: CounterMutation) => Promise<void>;\n}\n\n/**\n * Test-visible orchestrator. The production `handler` calls this with\n * real dependencies; unit tests inject fakes.\n */\nexport const runCounterMaintenance = async (\n  event: CounterMaintenanceEvent,\n  deps: CounterMaintenanceDependencies,\n): Promise<void> => {\n  const resolved = resolveEvent(event);\n  if (resolved === null) {\n    // Detail-type this consumer does not handle — the EventBridge rule\n    // should never deliver one. Treat as a no-op rather than throwing.\n    return;\n  }\n\n  // Dedup is the single circuit-breaker between EventBridge's\n  // at-least-once redelivery and the non-idempotent atomic ADDs below.\n  const recordResult = await deps.dedupClient.recordIfAbsent({\n    consumerName: COUNTER_MAINTENANCE_CONSUMER_NAME,\n    eventId: resolved.dedupKey.eventId,\n    attempt: resolved.dedupKey.attempt,\n  });\n  if (!recordResult.recorded) {\n    return;\n  }\n\n  try {\n    // Apply mutations sequentially. Each is an independent atomic ADD on\n    // a distinct canonical record; ordering does not matter for\n    // correctness, and sequential keeps the failure surface simple.\n    for (const mutation of resolved.mutations) {\n      await deps.applyMutation(mutation);\n    }\n  } catch (err) {\n    // Mark the dedup row failed so the replay tooling (TR-016 follow-up)\n    // can re-publish with a fresh attempt, then re-throw so EventBridge's\n    // failure-detection path (retry + DLQ + alarm) stays intact.\n    await deps.dedupClient.markFailed({\n      consumerName: COUNTER_MAINTENANCE_CONSUMER_NAME,\n      eventId: resolved.dedupKey.eventId,\n      attempt: resolved.dedupKey.attempt,\n      reason: errorMessage(err),\n    });\n    throw err;\n  }\n};\n\nconst productionDependencies = (): CounterMaintenanceDependencies => {\n  const dynamodb = new DynamoDBClient({});\n  return {\n    dedupClient: workflowDedupClient(dynamodb),\n    applyMutation: async (mutation) => {\n      await applyCounterDeltaOperation({ mutation });\n    },\n  };\n};\n\nexport const handler = async (event: CounterMaintenanceEvent): Promise<void> =>\n  runCounterMaintenance(event, productionDependencies());\n","import {\n  COUNTER_TARGET,\n  type CounterDelta,\n  type CounterMutation,\n  type WorkspaceCounter,\n} from \"./counter-apply-operation\";\nimport { isAdminRoleAssignment } from \"./role-admin-classification\";\n\n/**\n * ADR-028 event → counter-delta routing. Pure functions that translate\n * one decoded control-plane domain event into the set of atomic counter\n * deltas the counter-maintenance consumer must apply. Kept side-effect\n * free so the routing rules are unit-testable without a DynamoDB client.\n *\n * The membership scope discriminator is `workspaceId` set/unset (the\n * same ADR-018 sub-lane distinction the publisher carries):\n * - membership, `workspaceId` ABSENT (tenant-scoped) →\n *   `Tenant.usersInTenant` ±1 AND `User.tenantsForUser` ±1\n * - membership, `workspaceId` PRESENT (workspace-scoped) →\n *   `Workspace.usersInWorkspace` ±1 AND `User.workspacesForUser` ±1\n * - role-assignment, `workspaceId` PRESENT → admin/normal classified →\n *   `Workspace.adminUsersInWorkspace` ±1 OR `Workspace.normalUsersInWorkspace` ±1\n * - role-assignment, `workspaceId` ABSENT (tenant-level) → no counter\n * - workspace created/deleted → `Tenant.workspacesInTenant` ±1\n *\n * @see ADR-028 — Denormalized Control-Plane Membership Counters\n */\n\nexport type { CounterMutation };\n\n/** Membership / role-assignment / workspace event payload shapes the router reads. */\nexport interface MembershipChangedPayload {\n  readonly tenantId: string;\n  readonly userId?: string;\n  readonly workspaceId?: string;\n}\n\nexport interface RoleAssignmentChangedPayload {\n  readonly tenantId: string;\n  readonly userId?: string;\n  readonly workspaceId?: string;\n  readonly roleId?: string;\n  readonly roleLevel?: string;\n}\n\nexport interface WorkspaceChangedPayload {\n  readonly tenantId: string;\n  readonly workspaceId: string;\n}\n\n/**\n * Resolve the counter mutations for a membership create / delete.\n * `delta` is `+1` for created, `-1` for deleted.\n */\nexport function membershipMutations(\n  payload: MembershipChangedPayload,\n  delta: CounterDelta,\n): Array<CounterMutation> {\n  const mutations: Array<CounterMutation> = [];\n\n  if (payload.workspaceId !== undefined) {\n    // Workspace-scoped membership: users-in-workspace + workspaces-for-user.\n    mutations.push({\n      target: COUNTER_TARGET.Workspace,\n      tenantId: payload.tenantId,\n      workspaceId: payload.workspaceId,\n      attribute: \"usersInWorkspace\",\n      delta,\n    });\n    if (payload.userId !== undefined) {\n      mutations.push({\n        target: COUNTER_TARGET.User,\n        userId: payload.userId,\n        attribute: \"workspacesForUser\",\n        delta,\n      });\n    }\n    return mutations;\n  }\n\n  // Tenant-scoped membership: users-in-tenant + tenants-for-user.\n  mutations.push({\n    target: COUNTER_TARGET.Tenant,\n    tenantId: payload.tenantId,\n    attribute: \"usersInTenant\",\n    delta,\n  });\n  if (payload.userId !== undefined) {\n    mutations.push({\n      target: COUNTER_TARGET.User,\n      userId: payload.userId,\n      attribute: \"tenantsForUser\",\n      delta,\n    });\n  }\n  return mutations;\n}\n\n/**\n * Resolve the counter mutations for a role-assignment create / delete.\n * Only workspace-scoped assignments drive a counter; tenant-level\n * assignments return no mutations. The admin/normal bucket is chosen by\n * the centralized {@link isAdminRoleAssignment} predicate.\n */\nexport function roleAssignmentMutations(\n  payload: RoleAssignmentChangedPayload,\n  delta: CounterDelta,\n): Array<CounterMutation> {\n  if (payload.workspaceId === undefined) {\n    return [];\n  }\n\n  const attribute: WorkspaceCounter = isAdminRoleAssignment({\n    roleLevel: payload.roleLevel,\n    roleId: payload.roleId,\n  })\n    ? \"adminUsersInWorkspace\"\n    : \"normalUsersInWorkspace\";\n\n  return [\n    {\n      target: COUNTER_TARGET.Workspace,\n      tenantId: payload.tenantId,\n      workspaceId: payload.workspaceId,\n      attribute,\n      delta,\n    },\n  ];\n}\n\n/**\n * Resolve the counter mutation for a workspace create / delete:\n * `Tenant.workspacesInTenant` ±1.\n */\nexport function workspaceMutations(\n  payload: WorkspaceChangedPayload,\n  delta: CounterDelta,\n): Array<CounterMutation> {\n  return [\n    {\n      target: COUNTER_TARGET.Tenant,\n      tenantId: payload.tenantId,\n      attribute: \"workspacesInTenant\",\n      delta,\n    },\n  ];\n}\n"],"mappings":"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","names":["import_workflows"]}

package/lib/counter-reconciliation.handler.d.mts

@@ -0,0 +1,116 @@
+import { a as CounterTarget } from './counter-apply-operation-DZM3MIDm.mjs';
+
+/**
+ * ADR-028 counter reconciliation — recompute the denormalized
+ * control-plane counters from canonical data and repair drift.
+ *
+ * The atomic-ADD path ({@link applyCounterDeltaOperation}) maintains the
+ * counters incrementally off domain events, but events can be missed,
+ * replayed, or arrive after a record was created without one (rows that
+ * predate the counter work). This operation is the correctness backstop
+ * ADR-028 names: it ignores the current counter value, recomputes the
+ * true value from canonical records, and writes the absolute recomputed
+ * value back with a DynamoDB `SET` (not `ADD`). A `SET` repairs both
+ * directions of drift and backfills an absent / `0` attribute to its
+ * correct value in one write.
+ *
+ * Counter semantics recomputed here MUST match {@link counterEventRouter}:
+ *
+ * - `Tenant.usersInTenant` = # tenant-scoped Memberships in the tenant
+ *   (membership with NO workspace reference).
+ * - `Tenant.workspacesInTenant` = # Workspaces in the tenant.
+ * - `Workspace.usersInWorkspace` = # workspace-scoped Memberships for the workspace.
+ * - `Workspace.adminUsersInWorkspace` / `normalUsersInWorkspace` =
+ *   # workspace-scoped RoleAssignments for the workspace, bucketed by
+ *   {@link isAdminRoleAssignment} on the assignment's role level / role id.
+ * - `User.tenantsForUser` = # tenant-scoped Memberships for the user.
+ * - `User.workspacesForUser` = # workspace-scoped Memberships for the user.
+ *
+ * @see counter-apply-operation.ts — the incremental ADD path this reconciles against.
+ * @see counter-event-router.ts — the event → counter semantics this mirrors.
+ */
+/** One counter's old → new transition, recorded only when `old !== new`. */
+interface CounterDriftEntry {
+    /** Which canonical entity the counter lives on. */
+    readonly target: CounterTarget;
+    /** Identity of the canonical record (tenantId for Tenant, workspaceId for Workspace, userId for User). */
+    readonly id: string;
+    /** Tenant the record belongs to (Workspace only; omitted for Tenant / User). */
+    readonly tenantId?: string;
+    /** The counter attribute name. */
+    readonly counter: string;
+    /** The value found on the record before reconciliation (0 when the attribute was absent). */
+    readonly old: number;
+    /** The recomputed-from-canonical value written back. */
+    readonly new: number;
+}
+
+/**
+ * ADR-028 counter-reconciliation driver — walks every canonical Tenant,
+ * Workspace, and User, reconciles each record's denormalized counters
+ * against canonical data, and accumulates a single drift report.
+ *
+ * Enumeration reuses the existing GSI1-sharded list operations
+ * (`summary` mode — ids only, no per-record BatchGet hydration):
+ *
+ * - All Tenants via {@link listTenantsOperation}.
+ * - Per tenant, all Workspaces in that tenant via
+ *   {@link listWorkspacesOperation} (the workspace GSI1 partition is
+ *   tenant-scoped).
+ * - All Users via {@link listUsersOperation}.
+ *
+ * Each record is then handed to the matching per-target recompute
+ * ({@link reconcileTenantCountersOperation},
+ * {@link reconcileWorkspaceCountersOperation},
+ * {@link reconcileUserCountersOperation}), which owns the SET-back repair
+ * and returns the per-counter old → new drift it corrected.
+ *
+ * @see counter-reconcile-operation.ts — the per-target recompute + repair.
+ */
+/** Totals summarizing one reconciliation run, alongside the per-counter drift list. */
+interface CounterReconcileReport {
+    /** Every counter that changed across every record, in walk order. */
+    readonly drift: Array<CounterDriftEntry>;
+    /** How many canonical records of each kind were scanned. */
+    readonly scanned: {
+        readonly tenants: number;
+        readonly workspaces: number;
+        readonly users: number;
+    };
+    /** Total number of individual counters corrected (== `drift.length`). */
+    readonly countersCorrected: number;
+}
+
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/counter-reconciliation/counter-reconciliation-handler.md
+ *
+ * ADR-028 counter-reconciliation job handler. Invoked on demand (manual
+ * `aws lambda invoke`, an operator runbook, or a scheduled trigger) — not
+ * an EventBridge consumer. Walks every canonical Tenant / Workspace /
+ * User, recomputes the denormalized counters from canonical data, repairs
+ * any drift with a `SET` write, and logs the per-counter old → new drift
+ * report.
+ *
+ * Idempotent by construction: each per-target recompute writes the
+ * absolute recomputed value, so a second run over unchanged data corrects
+ * nothing and reports zero drift. That is why the job needs no dedup
+ * circuit-breaker (unlike the event-driven counter-maintenance consumer,
+ * whose atomic ADDs are not idempotent).
+ */
+/** Dependency seam for tests; production wires the real driver. */
+interface CounterReconciliationDependencies {
+    /**
+     * Run the full reconciliation sweep. Defaults to
+     * {@link reconcileAllCountersOperation}; tests inject a fake.
+     */
+    readonly reconcileAll: () => Promise<CounterReconcileReport>;
+}
+/**
+ * Test-visible orchestrator. The production `handler` calls this with the
+ * real driver; unit tests inject a fake. Returns the drift report so an
+ * invoker (or test) can assert on what was corrected.
+ */
+declare const runCounterReconciliation: (deps: CounterReconciliationDependencies) => Promise<CounterReconcileReport>;
+declare const handler: () => Promise<CounterReconcileReport>;
+
+export { type CounterReconciliationDependencies, handler, runCounterReconciliation };

package/lib/counter-reconciliation.handler.d.ts

@@ -0,0 +1,116 @@
+import { a as CounterTarget } from './counter-apply-operation-DZM3MIDm.js';
+
+/**
+ * ADR-028 counter reconciliation — recompute the denormalized
+ * control-plane counters from canonical data and repair drift.
+ *
+ * The atomic-ADD path ({@link applyCounterDeltaOperation}) maintains the
+ * counters incrementally off domain events, but events can be missed,
+ * replayed, or arrive after a record was created without one (rows that
+ * predate the counter work). This operation is the correctness backstop
+ * ADR-028 names: it ignores the current counter value, recomputes the
+ * true value from canonical records, and writes the absolute recomputed
+ * value back with a DynamoDB `SET` (not `ADD`). A `SET` repairs both
+ * directions of drift and backfills an absent / `0` attribute to its
+ * correct value in one write.
+ *
+ * Counter semantics recomputed here MUST match {@link counterEventRouter}:
+ *
+ * - `Tenant.usersInTenant` = # tenant-scoped Memberships in the tenant
+ *   (membership with NO workspace reference).
+ * - `Tenant.workspacesInTenant` = # Workspaces in the tenant.
+ * - `Workspace.usersInWorkspace` = # workspace-scoped Memberships for the workspace.
+ * - `Workspace.adminUsersInWorkspace` / `normalUsersInWorkspace` =
+ *   # workspace-scoped RoleAssignments for the workspace, bucketed by
+ *   {@link isAdminRoleAssignment} on the assignment's role level / role id.
+ * - `User.tenantsForUser` = # tenant-scoped Memberships for the user.
+ * - `User.workspacesForUser` = # workspace-scoped Memberships for the user.
+ *
+ * @see counter-apply-operation.ts — the incremental ADD path this reconciles against.
+ * @see counter-event-router.ts — the event → counter semantics this mirrors.
+ */
+/** One counter's old → new transition, recorded only when `old !== new`. */
+interface CounterDriftEntry {
+    /** Which canonical entity the counter lives on. */
+    readonly target: CounterTarget;
+    /** Identity of the canonical record (tenantId for Tenant, workspaceId for Workspace, userId for User). */
+    readonly id: string;
+    /** Tenant the record belongs to (Workspace only; omitted for Tenant / User). */
+    readonly tenantId?: string;
+    /** The counter attribute name. */
+    readonly counter: string;
+    /** The value found on the record before reconciliation (0 when the attribute was absent). */
+    readonly old: number;
+    /** The recomputed-from-canonical value written back. */
+    readonly new: number;
+}
+
+/**
+ * ADR-028 counter-reconciliation driver — walks every canonical Tenant,
+ * Workspace, and User, reconciles each record's denormalized counters
+ * against canonical data, and accumulates a single drift report.
+ *
+ * Enumeration reuses the existing GSI1-sharded list operations
+ * (`summary` mode — ids only, no per-record BatchGet hydration):
+ *
+ * - All Tenants via {@link listTenantsOperation}.
+ * - Per tenant, all Workspaces in that tenant via
+ *   {@link listWorkspacesOperation} (the workspace GSI1 partition is
+ *   tenant-scoped).
+ * - All Users via {@link listUsersOperation}.
+ *
+ * Each record is then handed to the matching per-target recompute
+ * ({@link reconcileTenantCountersOperation},
+ * {@link reconcileWorkspaceCountersOperation},
+ * {@link reconcileUserCountersOperation}), which owns the SET-back repair
+ * and returns the per-counter old → new drift it corrected.
+ *
+ * @see counter-reconcile-operation.ts — the per-target recompute + repair.
+ */
+/** Totals summarizing one reconciliation run, alongside the per-counter drift list. */
+interface CounterReconcileReport {
+    /** Every counter that changed across every record, in walk order. */
+    readonly drift: Array<CounterDriftEntry>;
+    /** How many canonical records of each kind were scanned. */
+    readonly scanned: {
+        readonly tenants: number;
+        readonly workspaces: number;
+        readonly users: number;
+    };
+    /** Total number of individual counters corrected (== `drift.length`). */
+    readonly countersCorrected: number;
+}
+
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/counter-reconciliation/counter-reconciliation-handler.md
+ *
+ * ADR-028 counter-reconciliation job handler. Invoked on demand (manual
+ * `aws lambda invoke`, an operator runbook, or a scheduled trigger) — not
+ * an EventBridge consumer. Walks every canonical Tenant / Workspace /
+ * User, recomputes the denormalized counters from canonical data, repairs
+ * any drift with a `SET` write, and logs the per-counter old → new drift
+ * report.
+ *
+ * Idempotent by construction: each per-target recompute writes the
+ * absolute recomputed value, so a second run over unchanged data corrects
+ * nothing and reports zero drift. That is why the job needs no dedup
+ * circuit-breaker (unlike the event-driven counter-maintenance consumer,
+ * whose atomic ADDs are not idempotent).
+ */
+/** Dependency seam for tests; production wires the real driver. */
+interface CounterReconciliationDependencies {
+    /**
+     * Run the full reconciliation sweep. Defaults to
+     * {@link reconcileAllCountersOperation}; tests inject a fake.
+     */
+    readonly reconcileAll: () => Promise<CounterReconcileReport>;
+}
+/**
+ * Test-visible orchestrator. The production `handler` calls this with the
+ * real driver; unit tests inject a fake. Returns the drift report so an
+ * invoker (or test) can assert on what was corrected.
+ */
+declare const runCounterReconciliation: (deps: CounterReconciliationDependencies) => Promise<CounterReconcileReport>;
+declare const handler: () => Promise<CounterReconcileReport>;
+
+export { type CounterReconciliationDependencies, handler, runCounterReconciliation };