@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/src/errors/reasons.ts

@@ -1,102 +0,0 @@
-// Centralized registry of the reason codes the framework itself surfaces via
-// `details.reason`. Declaring them here keeps them typed + greppable, and
-// gives features a single source of truth when they need to branch on the
-// framework-level reason (e.g. "is this a stale-state race? retry once").
-//
-// Features add their own local Reasons objects (see `samples/errors/` or
-// `packages/bundled-features/src/tenant/constants.ts` → TenantErrors). The
-// framework deliberately does NOT enforce uniqueness across features — two
-// features may use the same reason string if the semantics match. The
-// convention: snake_case, no spaces, no feature prefix for framework reasons.
-//
-// AgentReasons below is a deliberate exception to "no feature prefix": those
-// reasons surface from the AI-agent runtime (tool dispatch, permission and
-// risk gates), not from a handler's own domain logic, and the `agent.`
-// prefix keeps them visibly distinct from FrameworkReasons in error payloads.
-// Both the docs site (`errors/` pages) and the enterprise repo read this same
-// source, so the prefix stays a naming convention here, not a new registry.
-
-export const FrameworkReasons = {
-  // ConflictError: atomic UPDATE lost the race (another writer moved the row
-  // between our snapshot and our WHERE clause). Client SDK default: toast +
-  // re-fetch.
-  staleState: "stale_state",
-
-  // UnprocessableError: guardTransition rejected a state-machine transition.
-  // Details carry `from`, `to`, and `validTargets` for debugging.
-  invalidTransition: "invalid_transition",
-
-  // AccessDeniedError: dispatcher's field-level write check blocked a field.
-  // Details carry `field` and `handler`.
-  fieldAccessDenied: "field_access_denied",
-
-  // ConflictError: cascade-delete guard refused because dependent rows exist.
-  // Details carry `blockingEntity`, `entity`, `entityId`.
-  deleteRestricted: "delete_restricted",
-
-  // FeatureDisabledError: handler's owning feature is globally disabled.
-  // Distinct from access-denied — clients should surface "feature X is
-  // currently unavailable" not "you don't have permission".
-  featureDisabled: "feature_disabled",
-
-  // AccessDeniedError: a handler/hook called ctx.queryAs/ctx.writeAs with a
-  // SYSTEM identity without an r.systemScope() feature or a declared escapeHatch.
-  systemIdentitySwitchDenied: "system_identity_switch_denied",
-
-  // AccessDeniedError: a handler/hook called ctx.queryAs/ctx.writeAs with a
-  // non-SYSTEM identity other than its own caller (different user, tenant,
-  // claims, origin or extra roles) without r.systemScope() or escapeHatch.
-  identitySwitchDenied: "identity_switch_denied",
-
-  // AccessDeniedError: a handler/hook called ctx.queryProjection(..., { unsafeAllTenants: true })
-  // without an r.systemScope() feature or a declared escapeHatch.
-  unsafeAllTenantsDenied: "unsafe_all_tenants_denied",
-
-  // AccessDeniedError: ctx.queryAsMember's userId is not an active member of
-  // ctx's tenant. Deliberately generic — a caller can't probe which check failed.
-  memberResolutionDenied: "member_resolution_denied",
-
-  // AccessDeniedError: a query handler invoked via ctx.queryAsMember tried to
-  // write — a resolved member principal is read-only by construction.
-  memberResolutionReadOnly: "member_resolution_read_only",
-
-  // AccessDeniedError: a write under an anonymous root touched a personal-data field
-  // without the root handler declaring access.personalData: "public-intake".
-  publicIntakeRequired: "public_intake_required",
-
-  // AccessDeniedError: the directly-dispatched entry handler performs a hard
-  // delete/forget but its agent.risk resolves below "high" — delegation via
-  // ctx.write/writeAs from a lower-risk handler does not inherit the gate.
-  irreversibleOperationRequiresHighRisk: "irreversible_operation_requires_high_risk",
-
-  // AccessDeniedError: the directly-dispatched entry handler writes a field
-  // flagged readAsInstruction: true but its agent.risk resolves below "high" —
-  // delegation via ctx.write/writeAs from a lower-risk handler does not
-  // inherit the gate.
-  instructionFieldWriteRequiresHighRisk: "instruction_field_write_requires_high_risk",
-} as const;
-
-export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];
-
-// Reason codes the AI-agent runtime surfaces via `details.reason`. Kept as a
-// sister catalog to FrameworkReasons instead of extending it — see the
-// file-header note above for why these carry the `agent.` prefix.
-export const AgentReasons = {
-  // AccessDeniedError: the agent called a tool name outside its allowed
-  // catalog for this run.
-  toolNotAllowed: "agent.tool_not_allowed",
-
-  // UnprocessableError: the agent loop hit its maximum round count before
-  // producing a final answer.
-  iterationLimit: "agent.iteration_limit",
-
-  // AccessDeniedError: the tool exists, but the caller's roles don't cover
-  // the handler behind it.
-  permissionDenied: "agent.permission_denied",
-
-  // AccessDeniedError: an `agent.risk: "high"` handler was invoked without
-  // the required explicit confirmation.
-  highRiskNoAlways: "agent.high_risk_no_always",
-} as const;
-
-export type AgentReason = (typeof AgentReasons)[keyof typeof AgentReasons];

package/src/errors/serialize.ts

@@ -1,136 +0,0 @@
-import type { KumikoError } from "./kumiko-error";
-
-// Wire format every 4xx/5xx response must match. The API routes use this
-// verbatim; keep it stable — the client SDK keys off these field names.
-//
-// `docsUrl` is the deep-link for self-service: default web/mobile renderers
-// show a "Mehr erfahren →" link pointing here. Computed from `details.reason`
-// (when set) or fallback to `code`. Always present, even when `details` is
-// stripped from the response (e.g. internal_error in production).
-export type ErrorResponseBody = {
-  readonly error: {
-    readonly code: string;
-    readonly i18nKey: string;
-    readonly i18nParams?: Readonly<Record<string, unknown>>;
-    readonly message: string;
-    readonly details?: unknown;
-    readonly docsUrl: string;
-    readonly requestId?: string;
-    readonly timestamp: string;
-  };
-};
-
-// InternalError deliberately omits `details` from the response in production,
-// because that field often carries the internal cause. The log still has
-// everything (see buildErrorLog).
-//
-// In dev/test the cause is exposed in the response body to make debugging
-// possible — without this, a crash in a handler comes back as a bare
-// "internal error" and developers have to add try/catch + UnprocessableError
-// just to see what went wrong (real footgun, not theoretical). The exposure
-// is gated on NODE_ENV !== "production" so a misconfigured prod deploy
-// doesn't leak stack traces over the wire.
-const CODES_WITHOUT_CLIENT_DETAILS = new Set(["internal_error"]);
-
-const isProductionEnv = (): boolean => process.env["NODE_ENV"] === "production";
-
-// Snapshot of the cause chain (top-most error only) suitable for inclusion
-// in dev-mode error responses. Stack is truncated to keep the body small.
-type DevCauseDetail = {
-  readonly causeName?: string;
-  readonly causeMessage?: string;
-  readonly causeStack?: string;
-};
-
-function devCauseDetail(cause: unknown): DevCauseDetail | undefined {
-  if (!(cause instanceof Error)) return undefined;
-  return {
-    causeName: cause.name,
-    causeMessage: cause.message,
-    ...(cause.stack && { causeStack: cause.stack.split("\n").slice(0, 8).join("\n") }),
-  };
-}
-
-export function serializeError(err: KumikoError, requestId?: string): ErrorResponseBody {
-  const stripped = CODES_WITHOUT_CLIENT_DETAILS.has(err.code) && isProductionEnv();
-  const exposeDeclaredDetails = err.details !== undefined && !stripped;
-
-  // For internal_error in dev/test, surface the cause chain so the
-  // response body has something useful instead of "internal error".
-  // Priority: declared details (if any) win over the cause snapshot —
-  // a hand-set details on InternalError should not be replaced.
-  const detailsForResponse = (() => {
-    if (exposeDeclaredDetails) return err.details;
-    if (CODES_WITHOUT_CLIENT_DETAILS.has(err.code) && !isProductionEnv()) {
-      return devCauseDetail(err.cause);
-    }
-    return undefined;
-  })();
-
-  return {
-    error: {
-      code: err.code,
-      i18nKey: err.i18nKey,
-      ...(err.i18nParams && { i18nParams: err.i18nParams }),
-      message: err.message,
-      ...(detailsForResponse !== undefined && { details: detailsForResponse }),
-      docsUrl: err.docsUrl,
-      ...(requestId && { requestId }),
-      timestamp: new Date().toISOString(),
-    },
-  };
-}
-
-// Full forensic shape — stack, cause chain, details — meant for the log
-// emitter. Callers should pipe this through a sensitive-value filter before it
-// leaves the process (out of scope for v1).
-export type ErrorLogEntry = {
-  readonly name: string;
-  readonly code: string;
-  readonly httpStatus: number;
-  readonly message: string;
-  readonly i18nKey: string;
-  readonly details?: unknown;
-  readonly stack?: string;
-  readonly cause?: CauseSnapshot;
-};
-
-export function buildErrorLog(err: KumikoError): ErrorLogEntry {
-  return {
-    name: err.name,
-    code: err.code,
-    httpStatus: err.httpStatus,
-    message: err.message,
-    i18nKey: err.i18nKey,
-    ...(err.details !== undefined && { details: err.details }),
-    ...(err.stack && { stack: err.stack }),
-    ...(err.cause !== undefined && { cause: serializeCause(err.cause) }),
-  };
-}
-
-// Recursive cause snapshot — follows error.cause.cause... until the chain
-// ends or a non-Error appears. Hard cap at 10 levels to avoid pathological
-// cyclic cause chains hanging the serializer.
-type CauseSnapshot = {
-  readonly name: string;
-  readonly message: string;
-  readonly stack?: string;
-  readonly cause?: CauseSnapshot;
-};
-
-const MAX_CAUSE_DEPTH = 10;
-
-function serializeCause(cause: unknown, depth = 0): CauseSnapshot {
-  if (depth >= MAX_CAUSE_DEPTH) {
-    return { name: "CauseChainTruncated", message: `depth >= ${MAX_CAUSE_DEPTH}` };
-  }
-  if (cause instanceof Error) {
-    return {
-      name: cause.name,
-      message: cause.message,
-      ...(cause.stack && { stack: cause.stack }),
-      ...(cause.cause !== undefined && { cause: serializeCause(cause.cause, depth + 1) }),
-    };
-  }
-  return { name: "NonError", message: String(cause) };
-}

package/src/errors/to-kumiko-error.ts

@@ -1,8 +0,0 @@
-import { InternalError } from "./classes";
-import { isKumikoError, type KumikoError } from "./kumiko-error";
-
-export function toKumikoError(e: unknown): KumikoError {
-  if (isKumikoError(e)) return e;
-  if (e instanceof Error) return new InternalError({ cause: e });
-  return new InternalError({ message: String(e) });
-}

package/src/errors/transition-details.ts

@@ -1,30 +0,0 @@
-// Gemeinsame Detail-Shape für invalid_transition-Errors. Beide Pfade
-// (state-machine.assertTransition + failTransition) müssen identisch
-// strukturierte Details liefern, sonst können HTTP-Clients den 422-Body
-// nicht uniform parsen — `from`/`to`/`allowed` sind die strukturierten
-// Felder, `message` ist die menschen-lesbare Form.
-//
-// Kein Re-Export von "validTargets" (CSV-string) mehr — wer CSV will
-// baut's via `allowed.join(", ")`. Eine Shape, ein Vertrag.
-
-export type InvalidTransitionDetails = {
-  readonly from: string;
-  readonly to: string;
-  readonly allowed: readonly string[];
-  readonly message: string;
-};
-
-export function buildInvalidTransitionDetails(
-  from: string,
-  to: string,
-  allowed: readonly string[],
-): InvalidTransitionDetails {
-  return {
-    from,
-    to,
-    allowed,
-    message: `Invalid transition: "${from}" → "${to}". Allowed from "${from}": ${
-      allowed.length > 0 ? allowed.join(", ") : "none"
-    }`,
-  };
-}

package/src/errors/write-error-info.ts

@@ -1,124 +0,0 @@
-import type {
-  WriteErrorInfo,
-  WriteFailure,
-} from "@cosmicdrift/kumiko-types/write-error-info-types";
-import { NotFoundError, UnprocessableError } from "./classes";
-import { KumikoError } from "./kumiko-error";
-import { FrameworkReasons } from "./reasons";
-import { buildInvalidTransitionDetails } from "./transition-details";
-
-// Re-exported so a caller importing this module directly (instead of via
-// the `./errors` barrel, which already re-exports these by name) still
-// gets the types — explicit, not a wildcard: this module isn't a public
-// subpath export (see package.json `exports`), so the only readers are
-// framework-internal.
-export type { WriteErrorInfo, WriteFailure };
-
-// Convenience for call sites that return a failed WriteResult. Keeps the
-// pattern `return writeFailure(new NotFoundError(...))` compact so handlers
-// and the CrudExecutor don't need to spell out the shape each time.
-export function writeFailure(err: KumikoError): WriteFailure {
-  return { isSuccess: false, error: toWriteErrorInfo(err) };
-}
-
-// Focused convenience for the two most common handler failures: "X not found"
-// (typed 404) and "business rule violated: REASON" (typed 422 with the reason
-// string surfaced in details.reason — the positional `reason` always wins
-// over a same-named key in `details`, so passing an unrelated `reason` there
-// by mistake can't shadow the slug). Reach for the concrete classes when you
-// need richer payload — these two cover the bulk of handler code.
-// @wrapper-known error-helper
-export function failNotFound(entity: string, id?: number | string): WriteFailure {
-  return writeFailure(new NotFoundError(entity, id));
-}
-
-// @wrapper-known error-helper
-export function failUnprocessable(
-  reason: string,
-  details?: Readonly<Record<string, unknown>> & { readonly reason?: never },
-): WriteFailure {
-  return writeFailure(new UnprocessableError(reason, details ? { details } : undefined));
-}
-
-/**
- * Convenience für State-Transition-Rejects: produces a WriteFailure mit
- * reason="invalid_transition" + strukturiertem `from`/`to`/`allowed`-
- * Detail-Block + lesbarer message. Pattern hat sich in publicstatus-
- * Maintenance + bestehenden state-machine-Helpers wiederholt — Helper
- * sammelt das in einem Aufruf statt drei manuelle Detail-Felder.
- *
- * `allowed` ist typisch `MAINTENANCE_TRANSITIONS.allowedFrom(from)`.
- */
-export function failTransition(from: string, to: string, allowed: readonly string[]): WriteFailure {
-  return writeFailure(
-    new UnprocessableError(FrameworkReasons.invalidTransition, {
-      i18nKey: "errors.invalidTransition",
-      details: buildInvalidTransitionDetails(from, to, allowed),
-    }),
-  );
-}
-
-// The cause travels out-of-band, keyed on the info object's identity: a field
-// on WriteErrorInfo would leak the underlying Error into the /batch failure
-// body and the idempotency cache, both of which serialize the info to JSON.
-// A cache replay yields a fresh object without an entry, so no cause there.
-const causeByWriteErrorInfo = new WeakMap<WriteErrorInfo, Error>();
-
-export function toWriteErrorInfo(err: KumikoError): WriteErrorInfo {
-  // In dev/test surface the cause-snapshot through `details` so the
-  // HTTP response carries something useful. Without this, internal_error
-  // crashes round-trip through WriteErrorInfo (no cause field) and come
-  // back to the client as a bare `{ message: "internal error" }` —
-  // identical user-experience to a misconfigured prod, just slower
-  // because the dev has to add try/catch + console.log to find the
-  // actual stack. Same gating as serializeError: NODE_ENV !== production.
-  const causeDetails =
-    err.details === undefined && err.code === "internal_error" && err.cause instanceof Error
-      ? process.env["NODE_ENV"] !== "production"
-        ? {
-            causeName: err.cause.name,
-            causeMessage: err.cause.message,
-            ...(err.cause.stack && {
-              causeStack: err.cause.stack.split("\n").slice(0, 8).join("\n"),
-            }),
-          }
-        : undefined
-      : undefined;
-  const effectiveDetails = err.details ?? causeDetails;
-  const info: WriteErrorInfo = {
-    code: err.code,
-    httpStatus: err.httpStatus,
-    i18nKey: err.i18nKey,
-    message: err.message,
-    ...(err.i18nParams && { i18nParams: err.i18nParams }),
-    ...(effectiveDetails !== undefined && { details: effectiveDetails }),
-  };
-  if (err.cause instanceof Error) causeByWriteErrorInfo.set(info, err.cause);
-  return info;
-}
-
-// Reconstitutes an error from WriteErrorInfo so command() (throw-based) can
-// keep raising a KumikoError after the batch returned structural data. The
-// concrete subclass identity is lost here — callers can still read code /
-// httpStatus / details but `instanceof NotFoundError` won't work. That's OK:
-// the HTTP layer keys off code + httpStatus, not class identity.
-export function reraiseAsKumikoError(info: WriteErrorInfo): KumikoError {
-  return new ReraisedError(info, causeByWriteErrorInfo.get(info));
-}
-
-class ReraisedError extends KumikoError {
-  readonly code: string;
-  readonly httpStatus: number;
-
-  constructor(info: WriteErrorInfo, cause?: Error) {
-    super({
-      message: info.message,
-      i18nKey: info.i18nKey,
-      ...(info.i18nParams && { i18nParams: info.i18nParams }),
-      ...(info.details !== undefined && { details: info.details }),
-      ...(cause && { cause }),
-    });
-    this.code = info.code;
-    this.httpStatus = info.httpStatus;
-  }
-}

package/src/errors/zod-bridge.ts

@@ -1,62 +0,0 @@
-import type { ZodError, ZodIssue } from "zod";
-import { ValidationError } from "./classes";
-import type { FieldIssue } from "./field-issue";
-
-// Zod issues carry a .code and sometimes issue-specific params (min, max, etc).
-// We surface those under `params` so the client can render "must be at least N"
-// without re-parsing the message.
-//
-// Keep this list in sync with the issue-code matrix in classes.test.ts — that
-// test is what catches Zod upgrades introducing new param names.
-const ISSUE_PARAM_KEYS = [
-  "minimum",
-  "maximum",
-  "expected",
-  "received",
-  "type",
-  "inclusive",
-  "exact",
-  "keys",
-  // Zod 4 additions:
-  "format", // invalid_format (email, url, uuid, regex, ...)
-  "divisor", // not_multiple_of
-  "values", // invalid_value (enum / literal)
-  "pattern", // invalid_format with regex
-] as const;
-
-export function validationErrorFromZod(error: ZodError): ValidationError {
-  const fields = error.issues.map<FieldIssue>((issue) => {
-    const params = extractIssueParams(issue);
-    return {
-      path: issue.path.map(String).join(".") || "(root)",
-      code: issue.code,
-      i18nKey: resolveI18nKey(issue),
-      ...(params && { params }),
-    };
-  });
-  return new ValidationError({ fields }, { cause: error });
-}
-
-// `code: "custom"` is zod's catch-all for every superRefine/refine check;
-// left mechanical it'd collapse onto one generic key, so a superRefine can
-// set `params.i18nKey` to override it. Keep in sync with the client mirror
-// (packages/headless/src/form/zod-bridge.ts).
-function resolveI18nKey(issue: ZodIssue): string {
-  if (issue.code === "custom") {
-    const override = issue.params?.["i18nKey"];
-    if (typeof override === "string") return override;
-  }
-  return `errors.validation.${issue.code}`;
-}
-
-function extractIssueParams(issue: ZodIssue): Readonly<Record<string, unknown>> | undefined {
-  // ZodIssue is a discriminated union with variant-specific params (minimum,
-  // maximum, expected, …); reading them generically requires widening since
-  // the union members don't share an index signature.
-  const out: Record<string, unknown> = {};
-  const bag = issue as unknown as Record<string, unknown>; // @cast-boundary zod-issue
-  for (const key of ISSUE_PARAM_KEYS) {
-    if (bag[key] !== undefined) out[key] = bag[key];
-  }
-  return Object.keys(out).length > 0 ? out : undefined;
-}

package/src/es-ops/README.md

@@ -1,179 +0,0 @@
-# es-ops
-
-ES-Operations für Kumiko-Apps. Phase 1+1.5 liefert `seed-migrations` als file-basiertes Diff-and-Apply für Aggregate-State-Updates, die idempotent-Seeder nicht erfassen können.
-
-> **Phase 1 vs 1.5:** Phase 1 hatte den Foundation-Code, Phase 1.5 hat den ersten realen Driver-Use-Case durch (publicstatus admin-roles) und brachte: `tenantIdOverride` für Tenant-scope-Aggregates, Dry-Run-Validator für Handler-QNs, Deploy-Doku, lokales Smoke-Pattern. Pflicht-Lesen: [Retro](../../../../kumiko-platform/docs/plans/features/es-ops-phase1-retro.md).
-
-## Quick API
-
-```ts
-import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
-
-await runProdApp({
-  features: [...],
-  seedsDir: "./seeds",   // ← einzige Setup-Pflicht
-  // ...
-});
-```
-
-> **Phase 1 Scope:** `runProdApp`-only. `runDevApp`-Integration folgt in Phase 1.5 (braucht separaten Dispatcher-Bootstrap, der stack-typed ist). Für lokale Tests: laufe `bunx kumiko ops seed:status` gegen die Dev-DB um pending seeds zu sehen, dann `runProdApp` lokal mit DEV-Connection für Apply.
-
-```ts
-// seeds/2026-05-20-fix-admin-roles.ts
-import type { SeedMigration } from "@cosmicdrift/kumiko-framework/es-ops";
-
-export default {
-  description: "ergänze TenantAdmin-Rolle für admin@example.com",
-  run: async (ctx) => {
-    const admin = await ctx.findUserByEmail("admin@example.com");
-    if (!admin) return;
-    for (const m of await ctx.findMembershipsOfUser(admin.id)) {
-      if (m.roles.includes("TenantAdmin")) continue;
-      await ctx.systemWriteAs(
-        "tenant:write:update-member-roles",
-        { userId: admin.id, tenantId: m.tenantId, roles: [...m.roles, "TenantAdmin"] },
-        m.streamTenantId, // ← tenantIdOverride aus dem JOIN auf kumiko_events.v1
-      );
-    }
-  },
-} satisfies SeedMigration;
-```
-
-### Wann brauche ich `tenantIdOverride`?
-
-Faustregel: **wenn das Ziel-Aggregate via Tenant-User erstellt wurde, brauchst Du den Override.**
-
-| Aggregate-Typ | Stream-Tenant | `tenantIdOverride` |
-|---|---|---|
-| config-values (system-scope) | SYSTEM_TENANT | weglassen |
-| system text-content | SYSTEM_TENANT | weglassen |
-| tenant-membership | jeweiliger Stream-Tenant aus events.v1 | ✅ `m.streamTenantId` (NICHT `m.tenantId` — die beiden können divergieren!) |
-| App-Entity (orders, tasks, …) | Tenant-Stream | ✅ Tenant-Id aus dem Lookup |
-
-**Warum nicht `m.tenantId`?** read_tenant_memberships.tenant_id ist der payload-tenant (logisches Mitgliedschafts-Ziel), kumiko_events.tenant_id der v1-Row ist der stream-tenant (wo das Aggregate physisch lebt). seedTenantMembership mit `by=systemAdmin` lässt die zwei auseinanderlaufen — der Helper `findMembershipsOfUser` liefert beide getrennt, damit Seeds den richtigen wählen können.
-
-Ohne `tenantIdOverride` sucht der Executor den Stream gegen SYSTEM_TENANT → `version_conflict`. Memory: `feedback_event_store_tenant_consistency.md`.
-
-## Deployment-Anforderungen
-
-Wichtig — wird gerne übersehen:
-
-### Docker / Bun-Bundle
-
-Seeds werden zur Runtime via `await import(absolutePath)` geladen. Bun's Bundler strippt dynamic-import-Targets → seeds/-Tree muss **als raw-TS-Tree** ins Image kopiert werden:
-
-```dockerfile
-# Nach dem dist-server/-COPY:
-COPY --from=build --chown=app:app /app/seeds ./seeds
-```
-
-Plus: in der `bun build` Stage NICHT mit `--minify` durch die seed-Files laufen (sie sind keine Eingabe — der Bundler bundlet `bin/main.ts`, nicht das seeds-Verzeichnis).
-
-### Idempotenz-Pflicht
-
-Seed-Body läuft **NICHT** atomic mit dem Marker (siehe „Was NICHT garantiert ist" unten). Wenn ein Seed mid-way thrown wirft, sind die schon committed Events drin, der Marker aber nicht → Retry beim nächsten Boot. **Seeds müssen idempotent sein.**
-
-Standard-Pattern:
-```ts
-const memberships = await ctx.findMembershipsOfUser(adminId);
-for (const m of memberships) {
-  if (m.roles.includes("TenantAdmin")) continue; // ← check-then-write
-  await ctx.systemWriteAs(...);
-}
-```
-
-Anti-Pattern (NICHT idempotent):
-```ts
-for (let i = 0; i < 5; i++) {
-  await ctx.systemWriteAs("create-something", { ... }); // ← Re-Run produziert Duplikate
-}
-```
-
-### Multi-Replica-Boot
-
-`pg_advisory_xact_lock` sequentialisiert parallele Pod-Boots. Lock-Key ist global (`0x65736f70` / „esop"), nicht migration-spezifisch → bei N pending Migrationen läuft N-mal sequentiell, nicht parallel. Für die typische seed-Migration-Workload ist das schnell genug; bei sehr langen Migrationen (>30s) auf einem Multi-Replica-Stack: erst manuell als CLI-Step laufen lassen (`bunx kumiko ops seed:apply`), dann Pod-Rollout.
-
-### Lokaler Smoke vor Push
-
-Pflicht-Pattern: bevor Du seeds in main pushst, einmal lokal gegen Dev-DB den Boot-Loop laufen lassen. Siehe `samples/recipes/seed-migration/scripts/smoke.ts` als copy-paste-Template.
-
-## CLI
-
-```bash
-bunx kumiko ops seed:new <slug>    # scaffold seeds/<date>-<slug>.ts
-bunx kumiko ops seed:status        # was applied, was pending
-bunx kumiko ops seed:apply [--dry-run]  # pending applien (CLI-Pfad in Phase 1.5)
-```
-
-## Garantien
-
-| Garantie | Wie |
-|---|---|
-| **Single-Run** | Marker in `kumiko_es_operations` + `pg_advisory_xact_lock` sequentialisiert Multi-Replica-Boots |
-| **Marker-Atomicity** | Runner-Tx + Re-Check inside lock → Marker reflektiert "Run wurde wirklich attempted" |
-| **Order** | File-name = chronologische ID; Failure stoppt alle pending |
-| **ES-konform** | `systemWriteAs` ruft existing Handler → Events landen im Store |
-| **Recovery** | `skippable: true` + `KUMIKO_SKIP_ES_OPS_<ID>=1` env-flag für Notfall-Skip |
-| **Boot-skip** | `KUMIKO_SKIP_ES_OPS=1` env-var skipped alle pending (Debug-Boots) |
-
-### Was NICHT garantiert ist
-
-**Seed-Body ist NICHT atomic vs. den Marker.** `systemWriteAs` läuft durch den App-Dispatcher mit dessen eigener Tx-Verwaltung (separat von der Runner-Tx). Wenn ein Seed `systemWriteAs` 5× erfolgreich aufruft und dann throws, sind die 5 Events **committed**, der Marker aber **nicht** geschrieben. Beim nächsten Boot retried der Runner — Seeds müssen daher **idempotent** sein:
-
-```ts
-// Gut: skip wenn schon korrigiert
-for (const m of memberships) {
-  if (m.roles.includes("TenantAdmin")) continue;
-  await ctx.systemWriteAs(...);
-}
-
-// Schlecht: jeder Re-Run dupliziert
-for (const m of memberships) {
-  await ctx.systemWriteAs("create-something-new", ...); // double on retry!
-}
-```
-
-Die meisten realen Seeds sind natürlich idempotent (existing-Lookup → conditional-write). Volle End-to-End-Atomicity (write + marker im gleichen Tx) ist als Phase 1.5 vorgesehen — braucht Refactor wie der Dispatcher die outer-Tx übernimmt.
-
-## Architektur
-
-`packages/framework/src/es-ops/` enthält:
-
-| File | Zweck |
-|---|---|
-| `operations-schema.ts` | `kumiko_es_operations` table-definition + `createEsOperationsTable` helper |
-| `types.ts` | `SeedMigration` + `SeedMigrationContext` Public-API |
-| `runner.ts` | `runPendingSeedMigrations` — Diff + Tx + Marker |
-| `context.ts` | `createSeedMigrationContext` — Read-Helpers + `systemWriteAs` |
-| `index.ts` | barrel-export |
-
-Tabellen-Schema:
-
-```sql
-CREATE TABLE kumiko_es_operations (
-  id              TEXT PRIMARY KEY,
-  operation_type  TEXT NOT NULL,                -- "seed-migration" | (Phase 2+)
-  applied_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
-  duration_ms     INTEGER NOT NULL,
-  applied_by      TEXT NOT NULL,                -- "boot" | "cli" | "ci-pipeline"
-  notes           TEXT
-);
-```
-
-## Phase 2+
-
-`operation_type`-Discriminator lässt zukünftige Operations dieselbe Tabelle + dasselbe CLI-Pattern nutzen:
-
-- `projection-rebuild` — TRUNCATE read_* + Replay aus Events
-- `event-replay` — Notification re-send ohne DB-Write
-- `event-backfill` — Missing-Events für Pre-ES-Daten
-- `stream-migration` — Aggregate-Stream-Tenant-Move (Sysadmin-Bug)
-- `aggregate-rebuild` — Snapshot-Refresh
-
-Implementation: **on demand** (siehe `kumiko-platform/docs/plans/features/es-ops.md`).
-
-## Driver-Use-Case
-
-publicstatus' admin-Member hatte initial `roles: ["Admin"]`. Sprint Role-Naming-Drift ergänzte „TenantAdmin", aber der idempotent-Seeder skipped existing Memberships → DB-Drift. Phase 1 löst genau diese Klasse von Bugs.
-
-Siehe Sample: `samples/recipes/seed-migration/`.