@empire-builder-kit/nx 1.0.0-rc.37 → 1.0.0-rc.39

package/src/generators/slice/built-in-plan-key-value-cleanup.d.ts

@@ -0,0 +1,4 @@
+/** Native expiry housekeeping; cadence and pause remain owned by background policy. */
+export declare function renderKeyValueCleanupFiles(name: string): Readonly<Record<string, string>>;
+/** Lightweight adopter orchestration tests; real-child repository proof is separate. */
+export declare function renderKeyValueCleanupTests(): string;

package/src/generators/slice/built-in-plan-key-value-cleanup.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValueCleanupFiles = renderKeyValueCleanupFiles;
+exports.renderKeyValueCleanupTests = renderKeyValueCleanupTests;
+/** Native expiry housekeeping; cadence and pause remain owned by background policy. */
+function renderKeyValueCleanupFiles(name) {
+    return {
+        'async/inbox-cleanup.ts': `import { randomUUID } from 'node:crypto';
+import { createLogger, type Logger } from '@empire-builder-kit/runtime/logging';
+import { createMetricEmitter, type MetricEmitter } from '@empire-builder-kit/runtime/observability';
+import { dataStore } from '../data/key-value.js';
+import { cleanupProviderInbox } from './provider-inbox.js';
+import { createPerformancePersistence } from '../performance/persistence.js';
+
+interface Dependencies {
+  logger: Logger; metrics: MetricEmitter; now(): number;
+  store: typeof dataStore;
+}
+export function createInboxCleanupHandler(dependencies: Dependencies) {
+  return async (event: { id?: string } = {}) => {
+    const correlationId = event.id ?? randomUUID();
+    const deadline = dependencies.now() + 4 * 60_000;
+    const store = dependencies.store();
+    const performance = createPerformancePersistence(store, dependencies.now);
+    let reported = 0, pendingReports = false;
+    let reportFailure: unknown;
+    const emit = (metricName: string, namespace: string, value: number) => {
+      if (dependencies.metrics.emit({ namespace, metricName, unit: 'Count', value,
+        dimensions: { component: namespace === 'EBK/Performance' ? 'performance-load-cleanup' : 'inbox-cleanup',
+          feature: namespace === 'EBK/Performance' ? 'performance' : 'async-work',
+          operation: namespace === 'EBK/Performance' ? 'expiry-cleanup' : 'inbox-cleanup',
+          slice: '${name}', stage: process.env.EBK_STAGE ?? 'local' } }) === undefined)
+        throw new Error('cleanup-metric-delivery-failed');
+    };
+    const report = async () => {
+      try {
+        const result = await performance.reportDeadlines(count => emit(
+          'PerformanceLoadCleanupDeadlineBreaches', 'EBK/Performance', count));
+        reported += result.reported; pendingReports ||= result.continuationRequired;
+      } catch (error) { reportFailure ??= error; }
+    };
+    try {
+      // Telemetry failure retains reports but does not prevent physical expiry.
+      await report();
+      const inbox = await cleanupProviderInbox(store, new Date(dependencies.now()).toISOString(), dependencies.now, deadline);
+      const expired = await performance.expire({ deadline });
+      await report();
+      emit('InboxCleanupContinuationRequired', 'EBK/Async', inbox.continuationRequired ? 1 : 0);
+      emit('PerformanceLoadCleanupContinuationRequired', 'EBK/Performance', expired.continuationRequired ? 1 : 0);
+      // A page is not a global count. Emit zero only after a complete inventory;
+      // otherwise retain explicit continuation and inspected-page evidence.
+      if (inbox.completeScan) emit('InboxCleanupBacklog', 'EBK/Async', 0);
+      if (expired.completeScan) emit('PerformanceLoadCleanupBacklog', 'EBK/Performance', 0);
+      if (reportFailure !== undefined) throw reportFailure;
+      if (reported > 0 || pendingReports) throw new Error('performance-load-cleanup-deadline-breached');
+      const result = { inbox, performance: expired, reportedPerformanceDeadlineBreaches: reported,
+        outcome: inbox.completeScan && expired.completeScan ? 'converged' : 'continuation-required' };
+      dependencies.logger.info('Native inbox cleanup completed', { context: { correlationId },
+        attributes: result, outcome: result.outcome === 'converged' ? 'success' : 'unknown' });
+      return result;
+    } catch (error) {
+      dependencies.logger.error('Native inbox cleanup failed', { context: { correlationId }, error, outcome: 'failure' });
+      throw error;
+    }
+  };
+}
+export const handler = createInboxCleanupHandler({ store: dataStore, now: Date.now,
+  metrics: createMetricEmitter({}),
+  logger: createLogger({ component: 'inbox-cleanup', feature: 'async-work', operation: 'inbox-cleanup',
+    slice: '${name}', stage: process.env.EBK_STAGE ?? 'local', workspace: process.env.EBK_WORKSPACE ?? '${name}' }),
+});
+`,
+    };
+}
+/** Lightweight adopter orchestration tests; real-child repository proof is separate. */
+function renderKeyValueCleanupTests() {
+    return `  it('cleans an empty native inbox without SQL and preserves deadline telemetry', async () => {
+    const store = {
+      get: vi.fn().mockResolvedValue(null),
+      list: vi.fn().mockResolvedValue({ records: [] }),
+      commit: vi.fn().mockResolvedValue(undefined),
+    };
+    const metrics = { emit: vi.fn(() => ({})) };
+    const handler = createInboxCleanupHandler({ logger: logger as never, metrics: metrics as never,
+      now: () => Date.parse('2026-01-01T00:00:00.000Z'), store: (() => store) as never });
+    await expect(handler()).resolves.toMatchObject({ outcome: 'converged', reportedPerformanceDeadlineBreaches: 0 });
+    expect(store.commit).toHaveBeenCalledTimes(2);
+    expect(metrics.emit).toHaveBeenCalledWith(expect.objectContaining({ metricName: 'PerformanceLoadCleanupBacklog', value: 0 }));
+  });
+  it('never accepts cleanup after native transport or metric failure', async () => {
+    const store = { get: vi.fn().mockRejectedValue(new Error('native unavailable')),
+      list: vi.fn().mockResolvedValue({ records: [] }), commit: vi.fn() };
+    const handler = createInboxCleanupHandler({ logger: logger as never, metrics: { emit: vi.fn() } as never,
+      now: () => Date.parse('2026-01-01T00:00:00.000Z'), store: (() => store) as never });
+    await expect(handler()).rejects.toThrow('native unavailable');
+    expect(store.commit).not.toHaveBeenCalled();
+  });
+`;
+}
+//# sourceMappingURL=built-in-plan-key-value-cleanup.js.map

package/src/generators/slice/built-in-plan-key-value-consumer.d.ts

@@ -0,0 +1,4 @@
+/** Default event consumption uses native transactional inboxes, never SQL or TTL timing as authority. */
+export declare function renderKeyValueEventConsumer(name: string, pascalName: string, workspace: string): string;
+/** The public example publisher uses the same durable intents as domain writes. */
+export declare function renderKeyValueCreatedPublisher(pascalName: string, workspace: string): string;

package/src/generators/slice/built-in-plan-key-value-consumer.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValueEventConsumer = renderKeyValueEventConsumer;
+exports.renderKeyValueCreatedPublisher = renderKeyValueCreatedPublisher;
+const built_in_plan_shared_js_1 = require("./built-in-plan-shared.js");
+/** Default event consumption uses native transactional inboxes, never SQL or TTL timing as authority. */
+function renderKeyValueEventConsumer(name, pascalName, workspace) {
+    const prefix = (0, built_in_plan_shared_js_1.lowerCamelIdentifier)(pascalName);
+    return `import { lifecycleIdempotencyKey, parseDataLifecycleChangeEvent } from '@empire-builder-kit/runtime/data-lifecycle';
+import { parseSqsEventBridgeRecords, toEventLogContext } from '@empire-builder-kit/runtime/events';
+import type { KeyValueChange } from '@empire-builder-kit/runtime/key-value';
+import { createLogger } from '@empire-builder-kit/runtime/logging';
+import { ${prefix}AuthorizationActions } from '../authorization/policy.js';
+import { authorize${pascalName}InternalOperation } from '../authorization/runtime.js';
+import lifecycleConsumers from '../data/lifecycle-consumers.json' with { type: 'json' };
+import workContract from '../async/work-contract.json' with { type: 'json' };
+import { dataStore } from '../data/key-value.js';
+
+interface QueueRecord { body: string; messageId: string }
+interface QueueEvent { Records: QueueRecord[] }
+interface DownstreamCopy {
+  sourceSlice: string; pseudonymousKey: string; copyId: string; recipient: string;
+  purpose: 'lifecycle-reconciliation'; expiresAt: string; action: 'correction' | 'deletion';
+  holdRefs: string[]; status: 'reconciled' | 'deleted'; updatedAt: string;
+}
+const sources = lifecycleConsumers.acceptedSources;
+if (lifecycleConsumers.schemaVersion !== 1 || !Array.isArray(sources) || !sources.length || sources.length > 32 ||
+    new Set(sources).size !== sources.length || sources.some(source => !/^[a-z][a-z0-9-]{0,62}$/.test(source)))
+  throw new Error('Lifecycle consumer configuration must contain unique bounded Slice sources.');
+const lifecycleSources = new Set(sources);
+const replaySeconds = workContract.queue.idempotencyWindowSeconds;
+if (replaySeconds !== 2_592_000 || workContract.queue.conflictPolicy !== 'same-id-different-payload-fails')
+  throw new Error('Event consumer requires the declared Standard 30-day replay and conflict policy.');
+const plusSeconds = (value: string, seconds: number) => new Date(Date.parse(value) + seconds * 1_000).toISOString();
+
+function validDownstream(value: unknown, sourceSlice: string, pseudonymousKey: string): DownstreamCopy {
+  const copy = value as DownstreamCopy;
+  if (!copy || copy.sourceSlice !== sourceSlice || copy.pseudonymousKey !== pseudonymousKey ||
+      copy.copyId !== '${name}-lifecycle-consumer' || copy.recipient !== '${name}' ||
+      copy.purpose !== 'lifecycle-reconciliation' || !Number.isFinite(Date.parse(copy.updatedAt)) ||
+      new Date(copy.updatedAt).toISOString() !== copy.updatedAt ||
+      !['correction', 'deletion'].includes(copy.action) ||
+      copy.status !== (copy.action === 'deletion' ? 'deleted' : 'reconciled') ||
+      !Array.isArray(copy.holdRefs) || copy.holdRefs.length !== 0)
+    throw new Error('Stored lifecycle copy is malformed or has a different scope.');
+  return copy;
+}
+
+export async function handler(event: QueueEvent) {
+  const workloadIdentity = process.env.EBK_WORKLOAD_IDENTITY;
+  if (workloadIdentity !== '${name}:event-consumer') throw new Error('Event consumer workload identity is invalid.');
+  const stage = process.env.EBK_STAGE;
+  if (!stage || !/^[a-z][a-z0-9-]{0,62}$/.test(stage))
+    throw new Error('Event consumer stage is required and must be exact.');
+  // A malformed envelope without a real SQS identity cannot be partially acknowledged.
+  if (!Array.isArray(event?.Records) || event.Records.length > 100 ||
+      new Set(event.Records.map(record => record.messageId)).size !== event.Records.length || event.Records.some(record =>
+      typeof record.messageId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(record.messageId) ||
+      typeof record.body !== 'string' || Buffer.byteLength(record.body) > 256 * 1024))
+    throw new Error('Event consumer requires a bounded batch with exact SQS message identities.');
+  const logger = createLogger({ component: 'event-consumer', feature: 'events', operation: 'consume-created',
+    slice: '${name}', stage, workspace: '${workspace}' });
+  const batch = parseSqsEventBridgeRecords(event.Records);
+  const failures = batch.failures.map(({ messageId }) => ({ itemIdentifier: messageId as string }));
+  for (const { detailType, envelope, messageId, source } of batch.events) {
+    try {
+      // Unspecified tenant metadata is the existing Standard application scope,
+      // not permission to select a different tenant. Multi-tenant features own
+      // their explicit consumer/persistence binding.
+      if (envelope.meta.stage !== stage || (envelope.meta.tenantId !== undefined && envelope.meta.tenantId !== 'application') ||
+          envelope.meta.schemaVersion !== 1 || Date.parse(envelope.meta.occurredAt) > Date.now() + 5 * 60 * 1_000)
+        throw new Error('Event scope, schema or time does not match the consumer.');
+      const changes: KeyValueChange[] = [];
+      const eventId = lifecycleIdempotencyKey('event-consumer', [source, envelope.meta.eventId]);
+      const replayWindowEndsAt = plusSeconds(envelope.meta.occurredAt, replaySeconds);
+      if (Date.parse(replayWindowEndsAt) < Date.now()) throw new Error('Event replay window has closed.');
+      const store = dataStore();
+      if (detailType === 'DataLifecycleChanged') {
+        const lifecycle = parseDataLifecycleChangeEvent(envelope.data);
+        if (lifecycle.sourceSlice !== source || !lifecycleSources.has(source) ||
+            lifecycle.categoryId !== 'product-record' || lifecycle.occurredAt !== envelope.meta.occurredAt)
+          throw new Error('Lifecycle event source, category or time is not declared by this consumer.');
+        await authorize${pascalName}InternalOperation({ action: ${prefix}AuthorizationActions.lifecycleConsume,
+          correlationId: envelope.meta.correlationId, operationId: messageId as string, workloadIdentity });
+        const copyId = lifecycleIdempotencyKey('lifecycle-copy', [source, lifecycle.pseudonymousKey, '${name}-lifecycle-consumer']);
+        const retained = await store.get('application', 'data-lifecycle-downstream-copies', copyId);
+        const previous = retained ? validDownstream(retained.value, source, lifecycle.pseudonymousKey) : null;
+        const expiresAt = plusSeconds(lifecycle.occurredAt, 400 * 24 * 60 * 60);
+        const newer = !previous || Date.parse(previous.updatedAt) < Date.parse(lifecycle.occurredAt) ||
+          (previous.updatedAt === lifecycle.occurredAt && previous.action !== 'deletion');
+        if (newer) changes.push({ action: 'put', collection: 'data-lifecycle-downstream-copies', id: copyId,
+          expectedVersion: retained?.version ?? 0, value: {
+            sourceSlice: source, pseudonymousKey: lifecycle.pseudonymousKey, copyId: '${name}-lifecycle-consumer',
+            recipient: '${name}', purpose: 'lifecycle-reconciliation', expiresAt,
+            action: lifecycle.action, holdRefs: [], status: lifecycle.action === 'deletion' ? 'deleted' : 'reconciled',
+            updatedAt: lifecycle.occurredAt,
+          } satisfies DownstreamCopy });
+        changes.push({ action: 'put', collection: 'data-lifecycle-receipts', id: eventId, expectedVersion: 0,
+          value: { ...lifecycle, expiresAt } });
+      } else {
+        const data = envelope.data as { id?: unknown; occurredBy?: unknown };
+        if (source !== '${name}' || detailType !== '${pascalName}Created' || !data || typeof data !== 'object' ||
+            Object.keys(data).sort().join(',') !== 'id,occurredBy' || typeof data.id !== 'string' ||
+            !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(data.id) ||
+            typeof data.occurredBy !== 'string' || !data.occurredBy || data.occurredBy.length > 128)
+          throw new Error('Event type, source or payload is not declared by this consumer.');
+      }
+      const result = await store.consume({ tenantId: 'application', consumer: 'event-consumer-v1', eventId,
+        payload: { source, detailType, envelope }, replayWindowEndsAt,
+        // Retain beyond the whole replay window; DynamoDB TTL is only physical cleanup.
+        expiresAt: plusSeconds(replayWindowEndsAt, 24 * 60 * 60), changes });
+      logger.info('${name} event consumed', { context: toEventLogContext(envelope.meta, detailType),
+        attributes: { result }, outcome: 'success' });
+    } catch {
+      failures.push({ itemIdentifier: messageId as string });
+    }
+  }
+  logger.info('${name} event batch completed', { attributes: { eventCount: batch.events.length, failureCount: failures.length },
+    outcome: failures.length ? 'failure' : 'success' });
+  return { batchItemFailures: failures };
+}
+`;
+}
+/** The public example publisher uses the same durable intents as domain writes. */
+function renderKeyValueCreatedPublisher(pascalName, workspace) {
+    const prefix = (0, built_in_plan_shared_js_1.lowerCamelIdentifier)(pascalName);
+    return `import { randomUUID } from 'node:crypto';
+import type { RuntimeHttpEvent } from '@empire-builder-kit/runtime';
+import type { Principal } from '@empire-builder-kit/runtime/auth';
+import { createContractHttpJsonHandler } from '@empire-builder-kit/runtime/api-server';
+import { buildEventEntry } from '@empire-builder-kit/runtime/events';
+import { authorize${pascalName}Operation } from '../authorization/runtime.js';
+import { ${prefix}PublishCreated } from './contracts/protected.js';
+import { ${pascalName}Created } from '../contracts/events.js';
+import { dataStore } from '../data/key-value.js';
+
+export const handler = createContractHttpJsonHandler<typeof ${prefix}PublishCreated, RuntimeHttpEvent, Principal>({
+  component: 'event-publisher', operation: ${prefix}PublishCreated, workspace: '${workspace}',
+  authorize: authorize${pascalName}Operation,
+  async handle({ context, principal }) {
+    const built = buildEventEntry(${pascalName}Created, { id: randomUUID(), occurredBy: principal.id }, {
+      busName: process.env.EVENT_BUS_NAME ?? '', stage: process.env.EBK_STAGE ?? '',
+      context: { ...context, tenantId: 'application' },
+    });
+    await dataStore().commit({ tenantId: 'application', changes: [], events: [built.entry] });
+    return { eventId: built.envelope.meta.eventId };
+  },
+});
+`;
+}
+//# sourceMappingURL=built-in-plan-key-value-consumer.js.map

package/src/generators/slice/built-in-plan-key-value-deletion.d.ts

@@ -0,0 +1,2 @@
+/** Same public deletion journey, backed by native item transactions and durable intents. */
+export declare function renderKeyValueDeletionFiles(name: string, pascalName: string, workspace: string): Readonly<Record<string, string>>;