@openhi/constructs 0.0.159 → 0.0.161

package/lib/counter-apply-operation-DZM3MIDm.d.mts

@@ -0,0 +1,63 @@
+/**
+ * ADR-028 atomic counter mutation against a canonical control-plane
+ * record. Each call applies one concurrency-safe DynamoDB `ADD` delta
+ * (`+1` on a relationship/lifecycle create, `-1` on delete) to a single
+ * named counter attribute on the canonical Tenant / Workspace / User row.
+ *
+ * The mutation goes through ElectroDB's `patch(key).add({ counter })`,
+ * which compiles to a DynamoDB `ADD` update expression — atomic, no
+ * read-modify-write. `patch` also stamps an `attribute_exists` guard on
+ * the partition key, so a counter is never written onto a phantom /
+ * deleted canonical record. Using ElectroDB (rather than a raw
+ * `UpdateItemCommand`) keeps the composite-key casing in lockstep with
+ * the entity definitions.
+ *
+ * Floor guard contract (ADR-028 § Floor guard): a `-1` against an
+ * absent / `0` counter is clamped to a no-op via a `.where(counter > 0)`
+ * condition — when the condition fails ElectroDB throws and the
+ * operation swallows it, returning `false`. The guard is a safety net,
+ * not the source of truth: ADR-028's reconciliation job recomputes the
+ * real value from canonical data and owns correctness.
+ *
+ * @see sites/www-docs/content/packages/@openhi/constructs/data/operations/control/counters/counter-apply-operation.md
+ */
+/** Counter attribute names per ADR-028, grouped by the canonical record they live on. */
+declare const TENANT_COUNTERS: readonly ["usersInTenant", "workspacesInTenant"];
+declare const WORKSPACE_COUNTERS: readonly ["usersInWorkspace", "adminUsersInWorkspace", "normalUsersInWorkspace"];
+declare const USER_COUNTERS: readonly ["tenantsForUser", "workspacesForUser"];
+type TenantCounter = (typeof TENANT_COUNTERS)[number];
+type WorkspaceCounter = (typeof WORKSPACE_COUNTERS)[number];
+type UserCounter = (typeof USER_COUNTERS)[number];
+/** The `+1` (create) / `-1` (delete) delta direction. */
+type CounterDelta = 1 | -1;
+/** Which canonical entity the counter lives on. */
+declare const COUNTER_TARGET: {
+    readonly Tenant: "Tenant";
+    readonly Workspace: "Workspace";
+    readonly User: "User";
+};
+type CounterTarget = (typeof COUNTER_TARGET)[keyof typeof COUNTER_TARGET];
+/**
+ * A resolved counter mutation: which canonical record (target + the
+ * ElectroDB composite-key fields that identify it), the attribute, and
+ * the delta. The router emits these; the operation applies them.
+ */
+type CounterMutation = {
+    readonly target: typeof COUNTER_TARGET.Tenant;
+    readonly tenantId: string;
+    readonly attribute: TenantCounter;
+    readonly delta: CounterDelta;
+} | {
+    readonly target: typeof COUNTER_TARGET.Workspace;
+    readonly tenantId: string;
+    readonly workspaceId: string;
+    readonly attribute: WorkspaceCounter;
+    readonly delta: CounterDelta;
+} | {
+    readonly target: typeof COUNTER_TARGET.User;
+    readonly userId: string;
+    readonly attribute: UserCounter;
+    readonly delta: CounterDelta;
+};
+
+export type { CounterMutation as C, CounterTarget as a };

package/lib/counter-apply-operation-DZM3MIDm.d.ts

@@ -0,0 +1,63 @@
+/**
+ * ADR-028 atomic counter mutation against a canonical control-plane
+ * record. Each call applies one concurrency-safe DynamoDB `ADD` delta
+ * (`+1` on a relationship/lifecycle create, `-1` on delete) to a single
+ * named counter attribute on the canonical Tenant / Workspace / User row.
+ *
+ * The mutation goes through ElectroDB's `patch(key).add({ counter })`,
+ * which compiles to a DynamoDB `ADD` update expression — atomic, no
+ * read-modify-write. `patch` also stamps an `attribute_exists` guard on
+ * the partition key, so a counter is never written onto a phantom /
+ * deleted canonical record. Using ElectroDB (rather than a raw
+ * `UpdateItemCommand`) keeps the composite-key casing in lockstep with
+ * the entity definitions.
+ *
+ * Floor guard contract (ADR-028 § Floor guard): a `-1` against an
+ * absent / `0` counter is clamped to a no-op via a `.where(counter > 0)`
+ * condition — when the condition fails ElectroDB throws and the
+ * operation swallows it, returning `false`. The guard is a safety net,
+ * not the source of truth: ADR-028's reconciliation job recomputes the
+ * real value from canonical data and owns correctness.
+ *
+ * @see sites/www-docs/content/packages/@openhi/constructs/data/operations/control/counters/counter-apply-operation.md
+ */
+/** Counter attribute names per ADR-028, grouped by the canonical record they live on. */
+declare const TENANT_COUNTERS: readonly ["usersInTenant", "workspacesInTenant"];
+declare const WORKSPACE_COUNTERS: readonly ["usersInWorkspace", "adminUsersInWorkspace", "normalUsersInWorkspace"];
+declare const USER_COUNTERS: readonly ["tenantsForUser", "workspacesForUser"];
+type TenantCounter = (typeof TENANT_COUNTERS)[number];
+type WorkspaceCounter = (typeof WORKSPACE_COUNTERS)[number];
+type UserCounter = (typeof USER_COUNTERS)[number];
+/** The `+1` (create) / `-1` (delete) delta direction. */
+type CounterDelta = 1 | -1;
+/** Which canonical entity the counter lives on. */
+declare const COUNTER_TARGET: {
+    readonly Tenant: "Tenant";
+    readonly Workspace: "Workspace";
+    readonly User: "User";
+};
+type CounterTarget = (typeof COUNTER_TARGET)[keyof typeof COUNTER_TARGET];
+/**
+ * A resolved counter mutation: which canonical record (target + the
+ * ElectroDB composite-key fields that identify it), the attribute, and
+ * the delta. The router emits these; the operation applies them.
+ */
+type CounterMutation = {
+    readonly target: typeof COUNTER_TARGET.Tenant;
+    readonly tenantId: string;
+    readonly attribute: TenantCounter;
+    readonly delta: CounterDelta;
+} | {
+    readonly target: typeof COUNTER_TARGET.Workspace;
+    readonly tenantId: string;
+    readonly workspaceId: string;
+    readonly attribute: WorkspaceCounter;
+    readonly delta: CounterDelta;
+} | {
+    readonly target: typeof COUNTER_TARGET.User;
+    readonly userId: string;
+    readonly attribute: UserCounter;
+    readonly delta: CounterDelta;
+};
+
+export type { CounterMutation as C, CounterTarget as a };

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

@@ -0,0 +1,38 @@
+import { WorkflowDedupClient } from '@openhi/workflows';
+import { EventBridgeEvent } from 'aws-lambda';
+import { C as CounterMutation } from './counter-apply-operation-DZM3MIDm.mjs';
+
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/counter-maintenance/counter-maintenance-handler.md
+ *
+ * ADR-028 counter-maintenance consumer. Invoked once per control-plane
+ * domain event on the control event bus. Dedupes the event on
+ * `(consumerName, eventId, attempt)` via the TR-015 `WorkflowDedupTable`,
+ * then applies the resolved atomic-ADD counter deltas to the affected
+ * canonical Tenant / Workspace / User records.
+ *
+ * Idempotency: an atomic ADD is not idempotent, so a replayed event must
+ * be a no-op. `recordIfAbsent` is the circuit-breaker — when it returns
+ * `recorded: false` a prior delivery of this exact `(eventId, attempt)`
+ * already applied the deltas, so the handler exits without re-applying.
+ * The dedup write happens-before the counter mutations, exactly as
+ * ADR-028 § Consume requires.
+ */
+type CounterMaintenanceEvent = EventBridgeEvent<string, unknown>;
+/** Dependency seam for tests; production wires the real dedup client. */
+interface CounterMaintenanceDependencies {
+    readonly dedupClient: WorkflowDedupClient;
+    /**
+     * Apply one resolved counter mutation. Defaults to
+     * {@link applyCounterDeltaOperation}; tests inject a spy.
+     */
+    readonly applyMutation: (mutation: CounterMutation) => Promise<void>;
+}
+/**
+ * Test-visible orchestrator. The production `handler` calls this with
+ * real dependencies; unit tests inject fakes.
+ */
+declare const runCounterMaintenance: (event: CounterMaintenanceEvent, deps: CounterMaintenanceDependencies) => Promise<void>;
+declare const handler: (event: CounterMaintenanceEvent) => Promise<void>;
+
+export { type CounterMaintenanceDependencies, handler, runCounterMaintenance };

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

@@ -0,0 +1,38 @@
+import { WorkflowDedupClient } from '@openhi/workflows';
+import { EventBridgeEvent } from 'aws-lambda';
+import { C as CounterMutation } from './counter-apply-operation-DZM3MIDm.js';
+
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/counter-maintenance/counter-maintenance-handler.md
+ *
+ * ADR-028 counter-maintenance consumer. Invoked once per control-plane
+ * domain event on the control event bus. Dedupes the event on
+ * `(consumerName, eventId, attempt)` via the TR-015 `WorkflowDedupTable`,
+ * then applies the resolved atomic-ADD counter deltas to the affected
+ * canonical Tenant / Workspace / User records.
+ *
+ * Idempotency: an atomic ADD is not idempotent, so a replayed event must
+ * be a no-op. `recordIfAbsent` is the circuit-breaker — when it returns
+ * `recorded: false` a prior delivery of this exact `(eventId, attempt)`
+ * already applied the deltas, so the handler exits without re-applying.
+ * The dedup write happens-before the counter mutations, exactly as
+ * ADR-028 § Consume requires.
+ */
+type CounterMaintenanceEvent = EventBridgeEvent<string, unknown>;
+/** Dependency seam for tests; production wires the real dedup client. */
+interface CounterMaintenanceDependencies {
+    readonly dedupClient: WorkflowDedupClient;
+    /**
+     * Apply one resolved counter mutation. Defaults to
+     * {@link applyCounterDeltaOperation}; tests inject a spy.
+     */
+    readonly applyMutation: (mutation: CounterMutation) => Promise<void>;
+}
+/**
+ * Test-visible orchestrator. The production `handler` calls this with
+ * real dependencies; unit tests inject fakes.
+ */
+declare const runCounterMaintenance: (event: CounterMaintenanceEvent, deps: CounterMaintenanceDependencies) => Promise<void>;
+declare const handler: (event: CounterMaintenanceEvent) => Promise<void>;
+
+export { type CounterMaintenanceDependencies, handler, runCounterMaintenance };