@empire-builder-kit/nx 1.0.0-rc.4 → 1.0.0-rc.40

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

@@ -0,0 +1,530 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValuePerformanceFiles = renderKeyValuePerformanceFiles;
+exports.renderKeyValueOutboxTests = renderKeyValueOutboxTests;
+exports.renderKeyValuePerformanceEndpointFunctions = renderKeyValuePerformanceEndpointFunctions;
+/** Protected test effects use native collections, never the application's records. */
+function renderKeyValuePerformanceFiles(name) {
+    return {
+        'performance/persistence.ts': `import { createHash } from 'node:crypto';
+import type { KeyValueChange } from '@empire-builder-kit/runtime/key-value';
+import type { ProtectedLoadRequestAuthorizationV1 } from '@empire-builder-kit/runtime/performance';
+import { dataStore } from '../data/key-value.js';
+
+type Authorization = ProtectedLoadRequestAuthorizationV1;
+type Store = ReturnType<typeof dataStore>;
+const RUNS = 'performance-runs';
+const TENANT = 'system';
+const EFFECT_RETENTION_MS = 24 * 60 * 60 * 1_000;
+const MAXIMUM_CLEANUP_EFFECTS = 1_000;
+const AUDIT_RETENTION_MS = 30 * 24 * 60 * 60 * 1_000;
+const CLEANUP_DEADLINE_MS = 24 * 60 * 60 * 1_000;
+const REPORTS = 'performance-cleanup-reports';
+interface Run {
+  schemaVersion: 1; planDigest: string; binding: string; runId: string;
+  adapterId: Authorization['adapterId']; createdAt: string; expiresAt: string;
+  cleanupStartedAt: string | null;
+}
+interface Claim { schemaVersion: 1; planDigest: string; ordinal: number; effectId: string | null }
+interface Effect {
+  schemaVersion: 1; planDigest: string; runId: string; effectId: string;
+  ordinal: number; kind: 'async' | 'database'; createdAt: string;
+  expiresAt: string; processedAt: string | null;
+}
+// Saturation is a bounded operational sample, never admission authority.
+// Share at most one in-flight/sample read per exact run in this warm process.
+const backlogSamples = new Map<string, { expiresAt: number; value: Promise<{ pendingEffects: number }> }>();
+function sampleKey(run: Run) { return JSON.stringify([process.env.EBK_KEY_VALUE_TABLE, process.env.EBK_STAGE, run.planDigest, run.binding]); }
+function timestamp(value: string): number {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value)
+    throw new Error('protected-performance-timestamp-invalid');
+  return time;
+}
+function digest(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+function conditionFailed(error: unknown): boolean {
+  return error instanceof Error && error.name === 'TransactionCanceledException' &&
+    (error as Error & { CancellationReasons?: { Code?: string }[] }).CancellationReasons?.some(
+      ({ Code }) => Code === 'ConditionalCheckFailed') === true;
+}
+function requests(plan: string) { return 'performance-requests-' + plan; }
+function effects(plan: string) { return 'performance-effects-' + plan; }
+function pendingEffects(plan: string) { return 'performance-pending-' + plan; }
+function runBinding(auth: Authorization): string {
+  return digest({ adapterId: auth.adapterId, configuredMaximum: auth.configuredMaximum,
+    createdAt: auth.createdAt, durationSeconds: auth.durationSeconds, expiresAt: auth.expiresAt,
+    maximumRequests: auth.maximumRequests, planDigest: auth.planMaterialDigest,
+    release: { candidateDigest: auth.release.candidateDigest, releaseId: auth.release.releaseId,
+      releaseMaterialDigest: auth.release.releaseMaterialDigest, sourceCommit: auth.release.sourceCommit },
+    runId: auth.runId, saturationSignalRef: auth.saturationSignalRef, scenarioId: auth.scenarioId,
+    stage: auth.stage, target: { accountFingerprint: auth.target.accountFingerprint,
+      endpoint: auth.operation === 'cleanup' ? auth.target.endpoint.replace(/\\/cleanup$/, '') : auth.target.endpoint,
+      region: auth.target.region, slice: auth.target.slice }, workload: auth.workload });
+}
+function validateAuthorization(auth: Authorization, now: number, operation: 'execute' | 'cleanup') {
+  // The endpoint authenticates the HMAC and complete deployment binding before
+  // calling this module. Keep lifetime, ordinal and operation checks here too:
+  // an invocation may cross expiry while awaiting a database response.
+  if (auth.operation !== operation || auth.stage !== process.env.EBK_STAGE ||
+      !/^[a-f0-9]{64}$/.test(auth.planMaterialDigest) ||
+      !Number.isSafeInteger(auth.maximumRequests) || auth.maximumRequests < 1 ||
+      !Number.isSafeInteger(auth.requestOrdinal) || auth.requestOrdinal < 1 ||
+      auth.requestOrdinal > auth.maximumRequests ||
+      !Number.isFinite(auth.configuredMaximum) || auth.configuredMaximum <= 0 ||
+      timestamp(auth.createdAt) > now || timestamp(auth.expiresAt) <= timestamp(auth.createdAt) ||
+      (operation === 'execute' && now >= timestamp(auth.expiresAt)))
+    throw new Error('protected-performance-authorization-invalid');
+}
+function readRun(value: unknown, plan: string): Run {
+  const run = value as Run;
+  if (!run || run.schemaVersion !== 1 || run.planDigest !== plan ||
+      !/^[a-f0-9]{64}$/.test(run.binding) || typeof run.runId !== 'string' ||
+      !['ebk-api-lambda-v1', 'ebk-dynamodb-async-v1', 'ebk-dynamodb-v1', 'ebk-service-v1'].includes(run.adapterId) ||
+      timestamp(run.expiresAt) <= timestamp(run.createdAt) ||
+      (run.cleanupStartedAt !== null && timestamp(run.cleanupStartedAt) < timestamp(run.createdAt)))
+    throw new Error('protected-performance-run-invalid');
+  return run;
+}
+function readEffect(value: unknown, id: string, run: Run): Effect {
+  const effect = value as Effect;
+  if (!effect || effect.schemaVersion !== 1 || effect.effectId !== id ||
+      !/^[a-f0-9]{64}$/.test(id) || effect.planDigest !== run.planDigest || effect.runId !== run.runId ||
+      !Number.isSafeInteger(effect.ordinal) || effect.ordinal < 1 ||
+      effect.kind !== (run.adapterId === 'ebk-dynamodb-async-v1' ? 'async' : 'database') ||
+      timestamp(effect.expiresAt) !== timestamp(effect.createdAt) + EFFECT_RETENTION_MS ||
+      timestamp(effect.createdAt) < timestamp(run.createdAt) ||
+      timestamp(effect.createdAt) >= timestamp(run.expiresAt) ||
+      (effect.processedAt !== null && timestamp(effect.processedAt) < timestamp(effect.createdAt)))
+    throw new Error('protected-performance-effect-collision');
+  return effect;
+}
+function checkRun(run: Run, version: number): KeyValueChange {
+  return { action: 'check', collection: RUNS, id: run.planDigest, expectedVersion: version };
+}
+
+export function createPerformancePersistence(store: Store, clock: () => number = Date.now) {
+  async function pendingDelete(effect: Effect, run: Run): Promise<KeyValueChange[]> {
+    if (effect.kind !== 'async' || effect.processedAt !== null) return [];
+    const row = await store.get(TENANT, pendingEffects(run.planDigest), effect.effectId);
+    if (!row || digest(readEffect(row.value, effect.effectId, run)) !== digest(effect))
+      throw new Error('protected-performance-backlog-invalid');
+    return [{ action: 'delete', collection: pendingEffects(run.planDigest), id: effect.effectId, expectedVersion: row.version }];
+  }
+  async function authorizedRun(auth: Authorization, closed: boolean) {
+    const row = await store.get(TENANT, RUNS, auth.planMaterialDigest);
+    const run = row ? readRun(row.value, auth.planMaterialDigest) : null;
+    if (!row || !run || run.binding !== runBinding(auth) || (!closed && run.cleanupStartedAt !== null))
+      throw new Error('protected-performance-run-collision');
+    return { run, version: row.version };
+  }
+  async function reserve(auth: Authorization): Promise<'claimed'> {
+    for (let retry = 0; retry < 3; retry++) {
+      validateAuthorization(auth, clock(), 'execute');
+      const row = await store.get(TENANT, RUNS, auth.planMaterialDigest);
+      const previous = row ? readRun(row.value, auth.planMaterialDigest) : null;
+      if (previous && (previous.binding !== runBinding(auth) || previous.cleanupStartedAt !== null))
+        throw new Error('protected-performance-run-collision');
+      const claim = await store.get(TENANT, requests(auth.planMaterialDigest), String(auth.requestOrdinal));
+      if (claim) throw new Error('protected-performance-request-replayed');
+      const run: Run = previous ?? { schemaVersion: 1, planDigest: auth.planMaterialDigest,
+        binding: runBinding(auth), runId: auth.runId, adapterId: auth.adapterId,
+        createdAt: auth.createdAt, expiresAt: auth.expiresAt, cleanupStartedAt: null };
+      validateAuthorization(auth, clock(), 'execute');
+      try {
+        await store.commit({ tenantId: TENANT, changes: [
+          previous ? checkRun(previous, row!.version) : { action: 'put', collection: RUNS,
+            id: run.planDigest, expectedVersion: 0, value: run },
+          { action: 'put', collection: requests(run.planDigest), id: String(auth.requestOrdinal),
+            expectedVersion: 0, value: { schemaVersion: 1, planDigest: run.planDigest,
+              ordinal: auth.requestOrdinal, effectId: auth.effectId } satisfies Claim },
+        ] });
+        return 'claimed';
+      } catch (error) { if (!conditionFailed(error)) throw error; }
+    }
+    throw new Error('protected-performance-request-conflict');
+  }
+  async function executeOnce(adapterId: 'ebk-dynamodb-async-v1' | 'ebk-dynamodb-v1',
+    effectId: string, auth: Authorization) {
+    validateAuthorization(auth, clock(), 'execute');
+    if (adapterId !== auth.adapterId || effectId !== auth.effectId || !/^[a-f0-9]{64}$/.test(effectId))
+      throw new Error('protected-performance-effect-collision');
+    const { run, version } = await authorizedRun(auth, false);
+    const claim = await store.get(TENANT, requests(run.planDigest), String(auth.requestOrdinal));
+    const claimed = claim?.value as Claim | undefined;
+    if (!claim || !claimed || claimed.schemaVersion !== 1 || claimed.planDigest !== run.planDigest ||
+        claimed.ordinal !== auth.requestOrdinal || claimed.effectId !== effectId)
+      throw new Error('protected-performance-request-unclaimed');
+    const previous = await store.get(TENANT, effects(run.planDigest), effectId);
+    if (previous) {
+      if (readEffect(previous.value, effectId, run).ordinal !== auth.requestOrdinal)
+        throw new Error('protected-performance-effect-collision');
+      // Even idempotent success must race safely with cleanup and a substituted claim.
+      validateAuthorization(auth, clock(), 'execute');
+      await store.commit({ tenantId: TENANT, changes: [checkRun(run, version),
+        { action: 'check', collection: requests(run.planDigest), id: String(auth.requestOrdinal), expectedVersion: claim.version },
+        { action: 'check', collection: effects(run.planDigest), id: effectId, expectedVersion: previous.version }] });
+      return { effectState: 'already-existed' as const };
+    }
+    const now = clock();
+    validateAuthorization(auth, now, 'execute');
+    const effect: Effect = { schemaVersion: 1, planDigest: run.planDigest, runId: run.runId,
+      effectId, ordinal: auth.requestOrdinal, kind: adapterId === 'ebk-dynamodb-async-v1' ? 'async' : 'database',
+      createdAt: new Date(now).toISOString(), expiresAt: new Date(now + EFFECT_RETENTION_MS).toISOString(), processedAt: null };
+    await store.commit({ tenantId: TENANT, changes: [
+      checkRun(run, version),
+      { action: 'check', collection: requests(run.planDigest), id: String(auth.requestOrdinal), expectedVersion: claim.version },
+      { action: 'put', collection: effects(run.planDigest), id: effectId, expectedVersion: 0, value: effect },
+      ...(effect.kind === 'async' ? [{ action: 'put' as const, collection: pendingEffects(run.planDigest), id: effectId, expectedVersion: 0, value: effect }] : [])] });
+    return { effectState: 'created' as const };
+  }
+  async function execute(adapterId: 'ebk-dynamodb-async-v1' | 'ebk-dynamodb-v1', effectId: string, auth: Authorization) {
+    for (let retry = 0; retry < 3; retry++) {
+      try { return await executeOnce(adapterId, effectId, auth); }
+      catch (error) { if (!conditionFailed(error)) throw error; }
+    }
+    throw new Error('protected-performance-effect-conflict');
+  }
+  async function observe(auth: Authorization) {
+    validateAuthorization(auth, clock(), 'execute');
+    const { run } = await authorizedRun(auth, false);
+    if (!auth.effectId) throw new Error('protected-performance-effect-collision');
+    const row = await store.get(TENANT, effects(run.planDigest), auth.effectId);
+    if (!row || readEffect(row.value, auth.effectId, run).ordinal !== auth.requestOrdinal)
+      throw new Error('protected-performance-effect-collision');
+    if (run.adapterId !== 'ebk-dynamodb-async-v1') return { pendingEffects: 0 };
+    // Pending markers are written/deleted atomically with their individual
+    // effects. Requests never rewrite the shared run admission/cleanup guard.
+    // The operational saturation sample stops at its configured 100% threshold;
+    // it is not a cross-page transactional count or mutation authority.
+    const key = sampleKey(run), cached = backlogSamples.get(key), now = clock();
+    if (cached && cached.expiresAt > now && cached.expiresAt <= now + 1000) return cached.value;
+    while (backlogSamples.size >= 32) backlogSamples.delete(backlogSamples.keys().next().value!);
+    const sample = { expiresAt: now + 1000, value: (async () => {
+      let count = 0, afterId: string | undefined;
+      do {
+        const page = await store.list(TENANT, pendingEffects(run.planDigest), { limit: 50, afterId });
+        for (const row of page.records) {
+          if (readEffect(row.value, row.id, run).processedAt !== null) throw new Error('protected-performance-backlog-invalid');
+          count++;
+        }
+        afterId = page.nextId;
+      } while (afterId && count < auth.configuredMaximum);
+      return { pendingEffects: count };
+    })() };
+    backlogSamples.set(key, sample);
+    try { return await sample.value; }
+    catch (error) { if (backlogSamples.get(key) === sample) backlogSamples.delete(key); throw error; }
+  }
+  async function close(auth: Authorization) {
+    validateAuthorization(auth, clock(), 'cleanup');
+    const row = await store.get(TENANT, RUNS, auth.planMaterialDigest);
+    const run = row ? readRun(row.value, auth.planMaterialDigest) : null;
+    if (run && run.binding !== runBinding(auth)) throw new Error('protected-performance-run-collision');
+    if (run && run.cleanupStartedAt !== null) return { run, version: row!.version };
+    const closed: Run = { schemaVersion: 1, planDigest: auth.planMaterialDigest,
+      binding: runBinding(auth), runId: auth.runId, adapterId: auth.adapterId,
+      createdAt: auth.createdAt, expiresAt: auth.expiresAt, cleanupStartedAt: new Date(clock()).toISOString() };
+    await store.commit({ tenantId: TENANT, changes: [{ action: 'put', collection: RUNS,
+      id: closed.planDigest, expectedVersion: row?.version ?? 0, value: closed }] });
+    return { run: closed, version: (row?.version ?? 0) + 1 };
+  }
+  async function cleanup(auth: Authorization) {
+    const { run, version } = await close(auth);
+    backlogSamples.delete(sampleKey(run));
+    const deadline = clock() + 5_000;
+    let removedEffectCount = 0;
+    for (;;) {
+      // Always consume the first remaining page: successful deletions shrink it.
+      const page = await store.list(TENANT, effects(run.planDigest), { limit: 10 });
+      if (page.records.length === 0) {
+        if ((await store.list(TENANT, pendingEffects(run.planDigest), { limit: 1 })).records.length)
+          throw new Error('protected-performance-backlog-invalid');
+        return { removedEffectCount, remainingEffectCount: 0 };
+      }
+      if (removedEffectCount + page.records.length > MAXIMUM_CLEANUP_EFFECTS || removedEffectCount > 0 && clock() >= deadline)
+        return { removedEffectCount, remainingEffectCount: null, complete: false as const };
+      const pending = (await Promise.all(page.records.map(row => pendingDelete(readEffect(row.value, row.id, run), run)))).flat();
+      await store.commit({ tenantId: TENANT, changes: [
+        checkRun(run, version), ...pending,
+        ...page.records.map((row): KeyValueChange => ({ action: 'delete', collection: effects(run.planDigest),
+          id: row.id, expectedVersion: row.version }))] });
+      removedEffectCount += page.records.length;
+    }
+  }
+  async function processAsync() {
+    const state = await store.get(TENANT, 'performance-maintenance', 'async-runs');
+    const value = state?.value as { afterId: string | null } | undefined;
+    if (state && (!value || (value.afterId !== null && !/^[a-f0-9]{64}$/.test(value.afterId))))
+      throw new Error('protected-performance-cursor-invalid');
+    const runs = await store.list(TENANT, RUNS, { limit: 10, afterId: value?.afterId ?? undefined });
+    let processed = 0;
+    let continuationRequired = runs.nextId !== undefined;
+    for (const row of runs.records) {
+      const run = readRun(row.value, row.id);
+      if (run.adapterId !== 'ebk-dynamodb-async-v1' || run.cleanupStartedAt !== null) continue;
+      const cursorId = 'async-' + row.id;
+      const cursor = await store.get(TENANT, 'performance-maintenance', cursorId);
+      const saved = cursor?.value as { afterId: string | null } | undefined;
+      if (cursor && (!saved || (saved.afterId !== null && !/^[a-f0-9]{64}$/.test(saved.afterId))))
+        throw new Error('protected-performance-cursor-invalid');
+      const page = await store.list(TENANT, effects(run.planDigest), { limit: 20, afterId: saved?.afterId ?? undefined });
+      continuationRequired ||= page.nextId !== undefined;
+      for (const effectRow of page.records) {
+        const effect = readEffect(effectRow.value, effectRow.id, run);
+        const now = clock();
+        if (effect.processedAt !== null || timestamp(effect.expiresAt) <= now) continue;
+        const current = await store.get(TENANT, RUNS, run.planDigest);
+        const active = current ? readRun(current.value, run.planDigest) : null;
+        if (!current || !active || active.binding !== run.binding || active.cleanupStartedAt !== null)
+          throw new Error('protected-performance-run-collision');
+        const pending = await pendingDelete(effect, active);
+        await store.commit({ tenantId: TENANT, changes: [
+          checkRun(active, current.version), ...pending,
+          { action: 'put', collection: effects(run.planDigest), id: effect.effectId, expectedVersion: effectRow.version,
+            value: { ...effect, processedAt: new Date(now).toISOString() } }] });
+        processed++;
+        backlogSamples.delete(sampleKey(run));
+      }
+      const checkpointRow = await store.get(TENANT, RUNS, run.planDigest);
+      if (!checkpointRow) continue;
+      const checkpoint = readRun(checkpointRow.value, run.planDigest);
+      if (checkpoint.cleanupStartedAt !== null) continue;
+      await store.commit({ tenantId: TENANT, changes: [checkRun(checkpoint, checkpointRow.version),
+        { action: 'put', collection: 'performance-maintenance',
+        id: cursorId, expectedVersion: cursor?.version ?? 0, value: { afterId: page.nextId ?? null } }] });
+    }
+    await store.commit({ tenantId: TENANT, changes: [{ action: 'put', collection: 'performance-maintenance',
+      id: 'async-runs', expectedVersion: state?.version ?? 0, value: { afterId: runs.nextId ?? null } }] });
+    return { processed, runs: runs.records.length, continuationRequired };
+  }
+  async function expire(options: { deadline?: number } = {}) {
+    const now = clock();
+    if (!Number.isFinite(now)) throw new Error('protected-performance-clock-invalid');
+    const state = await store.get(TENANT, 'performance-maintenance', 'expiry-runs');
+    const saved = state?.value as { afterId: string | null } | undefined;
+    if (state && (!saved || (saved.afterId !== null && !/^[a-f0-9]{64}$/.test(saved.afterId))))
+      throw new Error('protected-performance-cursor-invalid');
+    let removedEffects = 0, removedRequests = 0, removedRuns = 0;
+    let inspected = 0, inspectedRuns = 0, stateVersion = state?.version ?? 0;
+    let afterId = saved?.afterId ?? undefined, sawBeginning = afterId === undefined;
+    const deadline = Math.min(options.deadline ?? Infinity, now + 4 * 60_000);
+    if (!Number.isFinite(deadline)) throw new Error('protected-performance-clock-invalid');
+    const withinBudget = () => {
+      const current = clock();
+      if (!Number.isFinite(current) || current < now) throw new Error('protected-performance-clock-invalid');
+      return inspected < 5_000 && current < deadline;
+    };
+    const result = (completeScan: boolean) => ({ removedEffects, removedRequests, removedRuns,
+      inspectedRuns, inspected, continuationRequired: !completeScan, completeScan });
+    const savePosition = async (position: string | undefined) => {
+      await store.commit({ tenantId: TENANT, changes: [{ action: 'put', collection: 'performance-maintenance',
+        id: 'expiry-runs', expectedVersion: stateVersion, value: { afterId: position ?? null } }] });
+      stateVersion++; afterId = position;
+    };
+    while (withinBudget()) {
+      const page = await store.list(TENANT, RUNS, { limit: 10, afterId });
+      for (const row of page.records) {
+      if (!withinBudget()) return result(false);
+      inspected++; inspectedRuns++;
+      let run = readRun(row.value, row.id), version = row.version;
+      if (now < timestamp(run.expiresAt)) { await savePosition(row.id); continue; }
+      if (run.cleanupStartedAt === null) {
+        run = { ...run, cleanupStartedAt: new Date(now).toISOString() };
+        await store.commit({ tenantId: TENANT, changes: [{ action: 'put', collection: RUNS,
+          id: run.planDigest, expectedVersion: version, value: run }] });
+        version++;
+      }
+      const cursorId = 'expiry-' + run.planDigest;
+      const cursor = await store.get(TENANT, 'performance-maintenance', cursorId);
+      const position = cursor?.value as { afterId: string | null } | undefined;
+      if (cursor && (!position || (position.afterId !== null && !/^[a-f0-9]{64}$/.test(position.afterId))))
+        throw new Error('protected-performance-cursor-invalid');
+      let effectAfter = position?.afterId ?? undefined;
+      let effectBeginning = effectAfter === undefined, cursorVersion = cursor?.version ?? 0;
+      for (;;) {
+      if (!withinBudget()) return result(false);
+      // Seven effects leave room for exact effect/pending deletes, durable
+      // deadline reports and the run guard (at most 22 domain changes).
+      const selected = await store.list(TENANT, effects(run.planDigest), { limit: Math.min(7, 5_000 - inspected), afterId: effectAfter });
+      if (!withinBudget()) return result(false);
+      inspected += selected.records.length;
+      const changes: KeyValueChange[] = [];
+      let removed = 0;
+      for (const candidate of selected.records) {
+        const effect = readEffect(candidate.value, candidate.id, run);
+        if (timestamp(effect.expiresAt) > now) continue;
+        removed++;
+        changes.push(...await pendingDelete(effect, run));
+        changes.push({ action: 'delete', collection: effects(run.planDigest), id: effect.effectId,
+          expectedVersion: candidate.version });
+        const deadline = timestamp(effect.expiresAt) + CLEANUP_DEADLINE_MS;
+        if (now >= deadline) changes.push({ action: 'put', collection: REPORTS,
+          id: digest({ plan: run.planDigest, effect: effect.effectId }), expectedVersion: 0,
+          value: { schemaVersion: 1, planDigest: run.planDigest, effectId: effect.effectId,
+            deadlineAt: new Date(deadline).toISOString() } });
+      }
+      if (changes.length) {
+        changes.push(checkRun(run, version));
+        await store.commit({ tenantId: TENANT, changes });
+        removedEffects += removed;
+      }
+      await store.commit({ tenantId: TENANT, changes: [checkRun(run, version),
+        { action: 'put', collection: 'performance-maintenance', id: cursorId,
+          expectedVersion: cursorVersion, value: { afterId: selected.nextId ?? null } }] });
+      cursorVersion++; effectAfter = selected.nextId;
+      if (effectAfter !== undefined) continue;
+      if (!effectBeginning) { effectBeginning = true; continue; }
+      break;
+      }
+      if (now < timestamp(run.expiresAt) + AUDIT_RETENTION_MS) { await savePosition(row.id); continue; }
+      const remaining = await store.list(TENANT, effects(run.planDigest), { limit: 1 });
+      if (remaining.records.length) throw new Error('protected-performance-cleanup-incomplete');
+      if ((await store.list(TENANT, pendingEffects(run.planDigest), { limit: 1 })).records.length)
+        throw new Error('protected-performance-backlog-invalid');
+      for (;;) {
+      if (!withinBudget()) return result(false);
+      const claims = await store.list(TENANT, requests(run.planDigest), { limit: Math.min(20, 5_000 - inspected) });
+      inspected += claims.records.length;
+      if (claims.records.length) {
+        const deletes = claims.records.map((claim): KeyValueChange => {
+          const value = claim.value as Claim;
+          if (!value || value.schemaVersion !== 1 || value.planDigest !== run.planDigest ||
+              !Number.isSafeInteger(value.ordinal) || value.ordinal < 1 || String(value.ordinal) !== claim.id ||
+              (value.effectId !== null && !/^[a-f0-9]{64}$/.test(value.effectId)))
+            throw new Error('protected-performance-request-invalid');
+          return { action: 'delete', collection: requests(run.planDigest), id: claim.id, expectedVersion: claim.version };
+        });
+        await store.commit({ tenantId: TENANT, changes: [checkRun(run, version), ...deletes] });
+        removedRequests += deletes.length;
+        continue;
+      }
+      break;
+      }
+      const asyncCursor = await store.get(TENANT, 'performance-maintenance', 'async-' + run.planDigest);
+      await store.commit({ tenantId: TENANT, changes: [
+        { action: 'delete', collection: RUNS, id: run.planDigest, expectedVersion: version },
+        { action: 'delete', collection: 'performance-maintenance', id: cursorId, expectedVersion: cursorVersion },
+        ...(asyncCursor ? [{ action: 'delete' as const, collection: 'performance-maintenance',
+          id: 'async-' + run.planDigest, expectedVersion: asyncCursor.version }] : [])] });
+      removedRuns++;
+      await savePosition(row.id);
+      }
+      if (page.nextId === undefined) {
+        await savePosition(undefined);
+        if (sawBeginning) return result(true);
+        // A resumed sweep also covers the earlier prefix at this cutoff before
+        // it may emit a global zero. This is pagination, not TTL authority.
+        sawBeginning = true;
+      }
+    }
+    return result(false);
+  }
+  async function reportDeadlines(emit: (count: number) => void | Promise<void>) {
+    const page = await store.list(TENANT, REPORTS, { limit: 20 });
+    for (const row of page.records) {
+      const value = row.value as { schemaVersion: number; planDigest: string; effectId: string; deadlineAt: string };
+      if (!value || value.schemaVersion !== 1 || !/^[a-f0-9]{64}$/.test(value.planDigest) ||
+          !/^[a-f0-9]{64}$/.test(value.effectId) || timestamp(value.deadlineAt) > clock() ||
+          row.id !== digest({ plan: value.planDigest, effect: value.effectId }))
+        throw new Error('protected-performance-cleanup-report-invalid');
+    }
+    // At-least-once reporting: lost acknowledgement may repeat a metric, never
+    // erase an unreported breach or prevent physical cleanup on the next run.
+    await emit(page.records.length);
+    if (page.records.length) await store.commit({ tenantId: TENANT, changes: page.records.map(row => ({
+      action: 'delete' as const, collection: REPORTS, id: row.id, expectedVersion: row.version })) });
+    return { reported: page.records.length, continuationRequired: page.nextId !== undefined };
+  }
+  return { reserve, execute, observe, cleanup, processAsync, expire, reportDeadlines };
+}
+`,
+        'async/outbox-relay.ts': `import { randomUUID } from 'node:crypto';
+import { createLogger, type Logger } from '@empire-builder-kit/runtime/logging';
+import { dataStore } from '../data/key-value.js';
+import { createPerformancePersistence } from '../performance/persistence.js';
+
+// Domain intents use Streams and durable key-value reconciliation under the
+// same explicit outbox pause policy. This schedule owns the isolated test sink.
+export function createOutboxRelayHandler(dependencies: {
+  logger: Logger;
+  processPerformance: () => ReturnType<ReturnType<typeof createPerformancePersistence>['processAsync']>;
+}) {
+  return async function outboxRelay(event: { id?: string } = {}) {
+    const correlationId = event.id ?? randomUUID();
+    try {
+      const result = await dependencies.processPerformance();
+      dependencies.logger.info('Native async performance processing completed', {
+        context: { correlationId }, attributes: result,
+        outcome: result.continuationRequired ? 'unknown' : 'success',
+      });
+      return { failed: 0, published: 0, processedPerformance: result.processed,
+        outcome: result.continuationRequired ? 'continuation-required' : 'converged',
+        domainDelivery: 'key-value-stream-and-reconciliation' };
+    } catch (error) {
+      dependencies.logger.error('Native async performance processing failed', {
+        context: { correlationId }, error, outcome: 'failure',
+      });
+      throw error;
+    }
+  };
+}
+export const handler = createOutboxRelayHandler({
+  logger: createLogger({ component: 'outbox-relay', feature: 'async-work', operation: 'outbox-relay',
+    slice: '${name}', stage: process.env.EBK_STAGE ?? 'local', workspace: process.env.EBK_WORKSPACE ?? '${name}' }),
+  processPerformance: () => createPerformancePersistence(dataStore()).processAsync(),
+});
+`,
+    };
+}
+function renderKeyValueOutboxTests() {
+    return `  it('processes native protected effects without claiming to publish domain events', async () => {
+    const processPerformance = vi.fn().mockResolvedValue({ processed: 1, runs: 1, continuationRequired: false });
+    const handler = createOutboxRelayHandler({ logger: logger as never, processPerformance });
+    await expect(handler({ id: 'native-outbox' })).resolves.toMatchObject({
+      failed: 0, outcome: 'converged', processedPerformance: 1, published: 0,
+      domainDelivery: 'key-value-stream-and-reconciliation',
+    });
+    expect(processPerformance).toHaveBeenCalledTimes(1);
+  });
+  it('does not report complete processing after a partial page or a failed transaction', async () => {
+    const processPerformance = vi.fn().mockResolvedValue({ processed: 20, runs: 1, continuationRequired: true });
+    const handler = createOutboxRelayHandler({ logger: logger as never, processPerformance });
+    await expect(handler()).resolves.toMatchObject({ outcome: 'continuation-required' });
+    processPerformance.mockRejectedValueOnce(new Error('native transaction failed'));
+    await expect(handler()).rejects.toThrow('native transaction failed');
+    expect(logger.error).toHaveBeenCalledWith('Native async performance processing failed', expect.objectContaining({ outcome: 'failure' }));
+  });
+`;
+}
+/** The common protected HTTP shell owns HMAC, release, target and body limits. */
+function renderKeyValuePerformanceEndpointFunctions() {
+    return `function persistence() { return createPerformancePersistence(dataStore()); }
+export async function reserveRequest(authorization: ProtectedLoadRequestAuthorizationV1) {
+  return persistence().reserve(authorization);
+}
+export async function databaseExecution(
+  adapterId: 'ebk-dynamodb-async-v1' | 'ebk-dynamodb-v1', effectId: string,
+  authorization: ProtectedLoadRequestAuthorizationV1,
+) {
+  const started = performance.now();
+  const repository = persistence();
+  const result = await repository.execute(adapterId, effectId, authorization);
+  const observation = await repository.observe(authorization);
+  const elapsed = performance.now() - started;
+  if (!Number.isFinite(elapsed) || elapsed < 0) throw new Error('protected-performance-clock-invalid');
+  return { ...result, saturationPercent: Math.min(100, adapterId === 'ebk-dynamodb-async-v1'
+    ? observation.pendingEffects / authorization.configuredMaximum * 100
+    : elapsed / DYNAMODB_PROTECTED_REQUEST_BUDGET_MS * 100) };
+}
+export async function cleanupRun(
+  adapterId: 'ebk-dynamodb-async-v1' | 'ebk-dynamodb-v1',
+  authorization: ProtectedLoadRequestAuthorizationV1,
+) {
+  if (adapterId !== authorization.adapterId) throw new Error('protected-performance-adapter-invalid');
+  return persistence().cleanup(authorization);
+}
+`;
+}
+//# sourceMappingURL=built-in-plan-key-value-performance.js.map

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

@@ -0,0 +1,4 @@
+/** Native provider inbox. External effects remain at-least-once or require reconciliation. */
+export declare function renderKeyValueProviderFiles(name: string): Readonly<Record<string, string>>;
+/** Replace only the SQL-specific provider cases; other async acceptance stays mandatory. */
+export declare function renderKeyValueProviderTestCases(name: string): string;