@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/src/pipeline/event-retention.ts

@@ -1,144 +0,0 @@
-import type { DbConnection } from "../db/connection";
-import { lockEventConsumersShareMode } from "../db/queries/event-consumer";
-import { deleteMany, selectMany, transaction } from "../db/query";
-import { eventsTable } from "../event-store";
-import { eventConsumerStateTable } from "./event-consumer-state";
-
-// Retention for the events-table. Aggregate events are source of truth —
-// they power loadAggregate, projection rebuilds, asOf queries, audit.
-// Pruning them is destructive and cannot be reversed, so the caller MUST
-// name the aggregateTypes explicitly; there is no default.
-//
-// Typical use: ops prunes archived aggregate streams (see archive.ts) after
-// legal/compliance retention has elapsed, or drops a specific aggregate
-// type that's been deprecated and replaced.
-//
-// Safety guard: before deleting, we check every row in
-// `kumiko_event_consumers`. If the minimum `lastProcessedEventId` across
-// non-disabled consumers is below the largest event id we'd delete, we
-// refuse with ConsumerLagError. A lagging consumer must either catch up,
-// be disabled, or the retention call must opt around it; pruning past its
-// cursor would silently drop deliveries.
-//
-// No background scheduler: the framework exposes the function. Ops wires
-// it into a cron, BullMQ repeating job, or pg_cron entry — whatever the
-// deployment already runs. That keeps the framework dependency-free for
-// retention and lets ops reason about timing alongside existing jobs.
-
-export type PruneEventsOptions = {
-  // Delete events whose createdAt is strictly older than this.
-  // Pass EITHER olderThan (explicit Temporal.Instant) OR olderThanDays.
-  readonly olderThan?: Temporal.Instant;
-  readonly olderThanDays?: number;
-  // Which aggregateTypes to prune. REQUIRED and non-empty. There is no
-  // default — pruning the event log is destructive, so the caller has to
-  // name what they're destroying.
-  readonly aggregateTypes: readonly string[];
-  // Dry-run: compute what would be deleted, return count, delete nothing.
-  readonly dryRun?: boolean;
-};
-
-export type PruneEventsResult = {
-  readonly deletedCount: number;
-  readonly cutoff: Temporal.Instant;
-  readonly aggregateTypes: readonly string[];
-  readonly dryRun: boolean;
-};
-
-export class ConsumerLagError extends Error {
-  constructor(
-    readonly laggingConsumer: string,
-    readonly consumerCursor: bigint,
-    readonly maxCandidateId: bigint,
-  ) {
-    super(
-      `Consumer "${laggingConsumer}" is behind the prune candidates ` +
-        `(cursor=${consumerCursor}, max candidate event id=${maxCandidateId}). ` +
-        `Pruning would silently drop deliveries. Catch up, disable, or skip the consumer first.`,
-    );
-    this.name = "ConsumerLagError";
-  }
-}
-
-function resolveCutoff(opts: PruneEventsOptions): Temporal.Instant {
-  if (opts.olderThan) return opts.olderThan;
-  const days = opts.olderThanDays;
-  if (days === undefined || days <= 0) {
-    throw new Error(
-      "pruneEvents: pass olderThan (Temporal.Instant) or olderThanDays (positive number).",
-    );
-  }
-  return Temporal.Now.instant().subtract({ hours: days * 24 });
-}
-
-export async function pruneEvents(
-  db: DbConnection,
-  options: PruneEventsOptions,
-): Promise<PruneEventsResult> {
-  const cutoff = resolveCutoff(options);
-  if (!options.aggregateTypes || options.aggregateTypes.length === 0) {
-    throw new Error(
-      "pruneEvents: aggregateTypes is required and must be non-empty. Pruning the event log is destructive — name the aggregate types to delete explicitly.",
-    );
-  }
-  const aggregateTypes = options.aggregateTypes;
-  const dryRun = options.dryRun === true;
-
-  return transaction(db, async (tx) => {
-    // Serialise against consumer-bootstrap INSERTs. Without this, the race
-    // is: prune reads consumers (snapshot misses a consumer bootstrapping
-    // in a parallel tx) → consumer commits its row with
-    // lastProcessedEventId=0 → prune deletes events below its new cursor
-    // → first pass of the new consumer silently skips the deleted events.
-    //
-    // SHARE is the lightest table-mode that conflicts with ROW EXCLUSIVE
-    // (the mode INSERT/UPDATE/DELETE take). Concurrent INSERTs on the
-    // consumer table queue until this TX commits; concurrent UPDATEs
-    // (cursor advances) do too, but prune is measured in milliseconds and
-    // pausing cursor advances for that window is cheap insurance against
-    // a silent data-loss bug.
-    await lockEventConsumersShareMode(tx);
-
-    // Step 1 — collect candidate event ids.
-    const candidates = await selectMany<{ id: bigint }>(tx, eventsTable, {
-      aggregateType: [...aggregateTypes],
-      createdAt: { lt: cutoff },
-    });
-
-    if (candidates.length === 0) {
-      return { deletedCount: 0, cutoff, aggregateTypes, dryRun };
-    }
-
-    const maxCandidateId = candidates.reduce(
-      (acc, row) => (row.id > acc ? row.id : acc),
-      candidates[0]?.id ?? 0n,
-    );
-
-    // Step 2 — safety guard: check every ACTIVE consumer has moved past
-    // the candidate set. Disabled consumers are intentionally excluded —
-    // ops disables them precisely to park them while pruning happens.
-    // The SHARE lock above guarantees this SELECT sees a complete view:
-    // no new consumer can INSERT a fresh-cursor row between here and the
-    // DELETE below.
-    const activeConsumers = await selectMany<{
-      name: string;
-      lastProcessedEventId: bigint;
-    }>(tx, eventConsumerStateTable, { status: { ne: "disabled" } });
-
-    for (const consumer of activeConsumers) {
-      if (consumer.lastProcessedEventId < maxCandidateId) {
-        throw new ConsumerLagError(consumer.name, consumer.lastProcessedEventId, maxCandidateId);
-      }
-    }
-
-    if (dryRun) {
-      return { deletedCount: candidates.length, cutoff, aggregateTypes, dryRun: true };
-    }
-
-    // Step 3 — actual delete, bounded to the candidate set.
-    const candidateIds = candidates.map((c) => c.id);
-    await deleteMany(tx, eventsTable, { id: candidateIds });
-
-    return { deletedCount: candidateIds.length, cutoff, aggregateTypes, dryRun: false };
-  });
-}

package/src/pipeline/idempotency.ts

@@ -1,158 +0,0 @@
-import type Redis from "ioredis";
-import { InternalError } from "../errors";
-import { generateId } from "../utils";
-import { RedisKeys } from "./redis-keys";
-
-// Discriminated so a truthy "acquired" object can never be misread as a
-// cache hit by a callsite doing `if (result)` — the caller must switch on
-// `status`.
-export type IdempotencyCheckResult =
-  | { readonly status: "cached"; readonly result: string }
-  | { readonly status: "acquired"; readonly token: string };
-
-export type IdempotencyGuard = {
-  check(tenantId: string, userId: string, requestId: string): Promise<IdempotencyCheckResult>;
-  store(
-    tenantId: string,
-    userId: string,
-    requestId: string,
-    token: string,
-    result: unknown,
-  ): Promise<void>;
-  release(tenantId: string, userId: string, requestId: string, token: string): Promise<void>;
-};
-
-// Sentinel prefix stored under the key while the handler is running. Each
-// acquisition appends a unique token so store() can later prove it still
-// owns the lock it started with (see storeScript below) instead of blindly
-// overwriting whatever is currently there.
-const PENDING_PREFIX = "__pending__:";
-
-export function createIdempotencyGuard(
-  redis: Redis,
-  options: {
-    ttlSeconds?: number;
-    pendingTtlSeconds?: number;
-    waitTimeoutMs?: number;
-    pollIntervalMs?: number;
-  } = {},
-): IdempotencyGuard {
-  const ttl = options.ttlSeconds ?? 300;
-  // Max time a single handler is allowed to hold the in-progress lock before
-  // a parallel retry is allowed to try again. Short enough that a crashed
-  // handler doesn't permanently block retries, long enough to cover normal
-  // batch durations.
-  const pendingTtl = options.pendingTtlSeconds ?? 30;
-  // Must stay comfortably above pendingTtl: a wait shorter than the lock's
-  // own TTL makes a retry give up and re-run the handler while the original
-  // call is still legitimately in flight — the exact case this lock exists
-  // to prevent. Clamped rather than trusted so a misconfigured explicit
-  // option can't reintroduce that inversion.
-  const waitTimeoutMs = Math.max(options.waitTimeoutMs ?? 35_000, pendingTtl * 1000 + 5_000);
-  const pollIntervalMs = options.pollIntervalMs ?? 50;
-  const prefix = RedisKeys.idempotency;
-
-  // Atomic compare-and-swap: only persist the result if the key still holds
-  // the exact pending token this run acquired. If a parallel retry reclaimed
-  // an expired lock in the meantime, this is a no-op — the reclaiming run
-  // owns the key now and will persist the authoritative result itself.
-  const storeScript = `
-    if redis.call("get", KEYS[1]) == ARGV[1] then
-      redis.call("set", KEYS[1], ARGV[2], "EX", ARGV[3])
-      return 1
-    else
-      return 0
-    end
-  `;
-
-  // Same CAS guard as storeScript: only clear the lock if we still own it.
-  // A stale token (lock already reclaimed by a new owner) is a no-op.
-  const releaseScript = `
-    if redis.call("get", KEYS[1]) == ARGV[1] then
-      return redis.call("del", KEYS[1])
-    else
-      return 0
-    end
-  `;
-
-  async function tryAcquire(key: string): Promise<string | null> {
-    const token = `${PENDING_PREFIX}${generateId()}`;
-    const acquired = await redis.set(key, token, "EX", pendingTtl, "NX");
-    return acquired === "OK" ? token : null;
-  }
-
-  return {
-    // Returns:
-    //   { status: "acquired", token } — caller owns the in-progress lock,
-    //     proceed to run the handler and then call store() with this token.
-    //   { status: "cached", result }  — serialized result from a concurrent
-    //     or prior request; do not run the handler.
-    //
-    // The old behaviour (pure GET + SET-NX-store) let two parallel requests
-    // both see a cache miss, both execute side-effects, and only one persist
-    // the result. This version uses a pending-marker lock so the second caller
-    // waits for the first to finish and reuses its result.
-    async check(tenantId, userId, requestId) {
-      const key = `${prefix}${tenantId}:${userId}:${requestId}`;
-
-      const token = await tryAcquire(key);
-      if (token) return { status: "acquired", token };
-
-      // Lost the race. Poll until the lock holder stores a result, or the
-      // lock expires (handler crashed) and we can try again.
-      const deadline = Date.now() + waitTimeoutMs;
-      while (Date.now() < deadline) {
-        const value = await redis.get(key);
-        if (value === null || value.startsWith(PENDING_PREFIX)) {
-          if (value === null) {
-            // Lock expired before a result was stored — try to claim it
-            // ourselves and proceed as the new owner.
-            const reclaimed = await tryAcquire(key);
-            if (reclaimed) return { status: "acquired", token: reclaimed };
-          }
-          await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
-          continue;
-        }
-        return { status: "cached", result: value };
-      }
-
-      // Gave up waiting. By construction waitTimeoutMs > pendingTtl, so the
-      // lock must have expired already — make one last claim attempt rather
-      // than silently reporting ownership we never acquired (that would
-      // reintroduce the double-execute bug). If even that loses the race,
-      // fail loudly instead of running the handler a second time.
-      const finalValue = await redis.get(key);
-      if (finalValue !== null && !finalValue.startsWith(PENDING_PREFIX)) {
-        return { status: "cached", result: finalValue };
-      }
-      const lastResort = await tryAcquire(key);
-      if (lastResort) return { status: "acquired", token: lastResort };
-      throw new InternalError({
-        message: `idempotency lock contention: gave up waiting for requestId ${requestId}`,
-      });
-    },
-
-    async store(tenantId, userId, requestId, token, result) {
-      const key = `${prefix}${tenantId}:${userId}:${requestId}`;
-      // @cast-boundary db-operator — Lua EVAL return type is untyped in ioredis
-      const written = (await redis.eval(
-        storeScript,
-        1,
-        key,
-        token,
-        JSON.stringify(result),
-        String(ttl),
-      )) as number;
-      // written === 0 means another process reclaimed this key after our
-      // lock expired and is (or already did) persist its own result —
-      // silently skipping here is the fix: the old code did an unconditional
-      // SET and could stomp that fresher result with our stale one.
-      void written;
-    },
-
-    async release(tenantId, userId, requestId, token) {
-      const key = `${prefix}${tenantId}:${userId}:${requestId}`;
-      await redis.eval(releaseScript, 1, key, token);
-    },
-  };
-}

package/src/pipeline/index.ts

@@ -1,83 +0,0 @@
-export type { EscapeHatchReportWindow } from "../observability/escape-hatch-report";
-export {
-  createEscapeHatchReporter,
-  createEscapeHatchReportWindow,
-  ESCAPE_HATCH_USED_SIGNAL,
-  fallbackEscapeHatchReporter,
-  reportEscapeHatchUse,
-} from "../observability/escape-hatch-report";
-export type { ResolveAuthClaimsArgs } from "./auth-claims-resolver";
-export { resolveAuthClaims } from "./auth-claims-resolver";
-export { createCascadeDeleteHook } from "./cascade-handler";
-export type { Dispatcher } from "./dispatcher";
-export { createDispatcher, dispatcherToWriteRef } from "./dispatcher";
-export type { DistributedLock } from "./distributed-lock";
-export { createDistributedLock } from "./distributed-lock";
-export type { EntityCache, EntityCacheOptions } from "./entity-cache";
-export { createEntityCache } from "./entity-cache";
-export type { ConsumerStatus, PendingGapEntry } from "./event-consumer-state";
-export {
-  ConsumerStatuses,
-  createEventConsumerStateTable,
-  eventConsumerStateTable,
-  SHARED_INSTANCE_SENTINEL,
-} from "./event-consumer-state";
-export type { EventDedup } from "./event-dedup";
-export { createEventDedup } from "./event-dedup";
-export type {
-  ConsumerProgress,
-  ConsumerRecoveryState,
-  DispatcherPassResult,
-  EventConsumer,
-  EventConsumerBatchHandler,
-  EventConsumerHandler,
-  EventDispatcher,
-  EventDispatcherOptions,
-} from "./event-dispatcher";
-export {
-  createEventDispatcher,
-  disableConsumer,
-  enableConsumer,
-  getAllConsumerProgress,
-  getConsumerState,
-  listConsumersWithState,
-  restartConsumer,
-  skipPoisonEvent,
-} from "./event-dispatcher";
-export type { ConsumerCursor } from "./event-dispatcher-delivery";
-export { selectConsumerCursorForUpdate } from "./event-dispatcher-delivery";
-export type { PruneEventsOptions, PruneEventsResult } from "./event-retention";
-export { ConsumerLagError, pruneEvents } from "./event-retention";
-export type { IdempotencyGuard } from "./idempotency";
-export { createIdempotencyGuard } from "./idempotency";
-export {
-  assertInstructionFieldWriteAllowed,
-  assertIrreversibleOperationAllowed,
-  isIrreversibleEntityVerb,
-} from "./irreversible-operation-gate";
-export type { LifecycleHooks, SystemHookDef, SystemHooks } from "./lifecycle-pipeline";
-export { createLifecycleHooks } from "./lifecycle-pipeline";
-export type { MspRebuildDeps } from "./msp-rebuild";
-export { rebuildMultiStreamProjection } from "./msp-rebuild";
-export type { ProjectionProgress, RebuildResult } from "./projection-rebuild";
-export {
-  getAllProjectionProgress,
-  getProjectionState,
-  listProjectionsWithState,
-  rebuildProjection,
-} from "./projection-rebuild";
-export type { ProjectionStatus } from "./projection-state";
-export {
-  createProjectionStateTable,
-  ProjectionStatuses,
-  projectionStateTable,
-} from "./projection-state";
-export { runProjectionsForEvent } from "./projections-runner";
-export {
-  ACCESS_INVALIDATION_CONSUMER_NAME,
-  createAccessInvalidationEventConsumer,
-  createSearchEventConsumer,
-  createSseBroadcastEventConsumer,
-  SEARCH_CONSUMER_NAME,
-  SSE_BROADCAST_CONSUMER_NAME,
-} from "./system-hooks";

package/src/pipeline/irreversible-operation-gate.ts

@@ -1,76 +0,0 @@
-import { type RequestContextData, requestContext } from "../api/request-context";
-import type { EntityDefinition } from "../engine/types";
-import { AccessDeniedError, type FrameworkReason, FrameworkReasons } from "../errors";
-
-type EntryHandler = NonNullable<RequestContextData["entryHandler"]>;
-
-// forget hard-purges regardless of softDelete; delete is only irreversible
-// when the entity has no soft-delete recovery path.
-export function isIrreversibleEntityVerb(
-  verb: "delete" | "forget",
-  entity: EntityDefinition,
-): boolean {
-  return verb === "forget" || !entity.softDelete;
-}
-
-// The gate reads the directly dispatched entry handler; a write dispatched inside a deferred
-// context (afterCommit hook, job, consumer) gets its own entryHandler and is gated too. Direct
-// executor/KMS calls without one stay ungated in exactly three cases: deleting derived data
-// rebuildable from a reversible source (document-ingest-foundation's forget-extract-with-file-ref
-// consumer, re-created on fileRef.restored), pipelines started by a risk "high" handler or a
-// cron scan (forget cleanup, retention, tenant destroy), and the step-dispatcher erasing the
-// per-dispatch record key once the outcome is recorded. A deferred context can't return the
-// reason to the agent synchronously, so the gate sits at the primitives.
-function assertEntryHandlerHighRisk(args: {
-  reason: FrameworkReason;
-  buildMessage: (entryHandler: EntryHandler) => string;
-  details: Record<string, unknown>;
-}): void {
-  const entryHandler = requestContext.get()?.entryHandler;
-  // skip: no entry handler (see above) or the entry handler already resolves "high".
-  if (!entryHandler || entryHandler.risk === "high") return;
-  throw new AccessDeniedError({
-    message: args.buildMessage(entryHandler),
-    details: {
-      reason: args.reason,
-      handler: entryHandler.qn,
-      resolvedRisk: entryHandler.risk,
-      ...args.details,
-    },
-  });
-}
-
-export function assertIrreversibleOperationAllowed(operation: string): void {
-  assertEntryHandlerHighRisk({
-    reason: FrameworkReasons.irreversibleOperationRequiresHighRisk,
-    buildMessage: (entryHandler) =>
-      `Handler "${entryHandler.qn}" performs an irreversible ${operation} but resolves agent risk ` +
-      `"${entryHandler.risk}" — declare agent: { risk: "high" } on "${entryHandler.qn}". The ` +
-      "directly called handler must carry it; delegating via ctx.write/writeAs does not.",
-    details: { operation },
-  });
-}
-
-// Fields flagged readAsInstruction: true have their write payload presence checked here — the
-// same reasoning as assertIrreversibleOperationAllowed, but the irreversible property belongs to
-// the target field, not the verb. Presence in the payload (not a value comparison against the
-// loaded row) is the deliberate fail-closed choice — see kumiko-framework#3358.
-export function assertInstructionFieldWriteAllowed(
-  entityName: string,
-  verb: "create" | "update",
-  writtenFieldNames: readonly string[],
-  instructionFieldNames: readonly string[],
-): void {
-  const fields = writtenFieldNames.filter((name) => instructionFieldNames.includes(name));
-  // skip: the write touches no readAsInstruction field.
-  if (fields.length === 0) return;
-  assertEntryHandlerHighRisk({
-    reason: FrameworkReasons.instructionFieldWriteRequiresHighRisk,
-    buildMessage: (entryHandler) =>
-      `Handler "${entryHandler.qn}" ${verb}s "${entityName}" field(s) ${fields.join(", ")} ` +
-      `flagged readAsInstruction: true but resolves agent risk "${entryHandler.risk}" — declare ` +
-      `agent: { risk: "high" } on "${entryHandler.qn}". The directly called handler must carry ` +
-      "it; delegating via ctx.write/writeAs does not.",
-    details: { entityName, verb, fields },
-  });
-}