@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/errors/kumiko-error.js

@@ -0,0 +1,43 @@
+// Base class for every error the framework recognizes as a contract.
+// Anything that isn't a KumikoError is treated as an unexpected crash and
+// auto-wrapped into InternalError by the dispatcher — so the HTTP layer never
+// has to guess the status or the client-facing shape.
+// Default docs URL for self-service errors. Override via `KUMIKO_DOCS_URL`
+// (e.g. self-hosted customers pointing at their own docs instance).
+const DEFAULT_DOCS_BASE_URL = "https://docs.kumiko.rocks";
+const REASON_SLUG_RE = /^[a-z0-9_.-]+$/;
+function docsBaseUrl() {
+    return process.env["KUMIKO_DOCS_URL"] ?? DEFAULT_DOCS_BASE_URL;
+}
+export class KumikoError extends Error {
+    i18nKey;
+    i18nParams;
+    details;
+    constructor(input) {
+        super(input.message, input.cause ? { cause: input.cause } : undefined);
+        this.name = new.target.name;
+        this.i18nKey = input.i18nKey;
+        this.i18nParams = input.i18nParams;
+        this.details = input.details;
+    }
+    // Docs URL for self-service. Prefer a well-formed `details.reason` slug
+    // (e.g. ConflictError → "stale_state"); otherwise fall back to the error
+    // code. Encode the path segment so spaces/`../` in free-form reasons
+    // cannot break or redirect the link the default renderer shows.
+    get docsUrl() {
+        return `${docsBaseUrl()}/errors/${encodeURIComponent(this.reasonSlug)}`;
+    }
+    get reasonSlug() {
+        if (this.details && typeof this.details === "object") {
+            // @cast-boundary error-details — per-error typed details; reflection
+            // shape only for the reasonSlug lookup.
+            const r = this.details["reason"];
+            if (typeof r === "string" && REASON_SLUG_RE.test(r))
+                return r;
+        }
+        return this.code;
+    }
+}
+export function isKumikoError(e) {
+    return e instanceof KumikoError;
+}

package/dist/errors/member-resolution.d.ts

@@ -0,0 +1,2 @@
+import { AccessDeniedError } from "./classes.js";
+export declare function memberResolutionReadOnlyDenied(cause?: unknown): AccessDeniedError;

package/dist/errors/member-resolution.js

@@ -0,0 +1,10 @@
+import { AccessDeniedError } from "./classes.js";
+import { FrameworkReasons } from "./reasons.js";
+// Lives in errors/ (not pipeline/) so db/tenant-db.ts can throw it without importing pipeline.
+export function memberResolutionReadOnlyDenied(cause) {
+    return new AccessDeniedError({
+        message: "a resolved member principal (ctx.queryAsMember) cannot write or reach raw SQL — read-only",
+        details: { reason: FrameworkReasons.memberResolutionReadOnly },
+        ...(cause instanceof Error && { cause }),
+    });
+}

package/dist/errors/reasons.d.ts

@@ -0,0 +1,23 @@
+export declare const FrameworkReasons: {
+    readonly staleState: "stale_state";
+    readonly invalidTransition: "invalid_transition";
+    readonly fieldAccessDenied: "field_access_denied";
+    readonly deleteRestricted: "delete_restricted";
+    readonly featureDisabled: "feature_disabled";
+    readonly systemIdentitySwitchDenied: "system_identity_switch_denied";
+    readonly identitySwitchDenied: "identity_switch_denied";
+    readonly unsafeAllTenantsDenied: "unsafe_all_tenants_denied";
+    readonly memberResolutionDenied: "member_resolution_denied";
+    readonly memberResolutionReadOnly: "member_resolution_read_only";
+    readonly publicIntakeRequired: "public_intake_required";
+    readonly irreversibleOperationRequiresHighRisk: "irreversible_operation_requires_high_risk";
+    readonly instructionFieldWriteRequiresHighRisk: "instruction_field_write_requires_high_risk";
+};
+export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];
+export declare const AgentReasons: {
+    readonly toolNotAllowed: "agent.tool_not_allowed";
+    readonly iterationLimit: "agent.iteration_limit";
+    readonly permissionDenied: "agent.permission_denied";
+    readonly highRiskNoAlways: "agent.high_risk_no_always";
+};
+export type AgentReason = (typeof AgentReasons)[keyof typeof AgentReasons];

package/dist/errors/reasons.js

@@ -0,0 +1,81 @@
+// 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",
+};
+// 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",
+};

package/dist/errors/serialize.d.ts

@@ -0,0 +1,32 @@
+import type { KumikoError } from "./kumiko-error.js";
+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;
+    };
+};
+export declare function serializeError(err: KumikoError, requestId?: string): ErrorResponseBody;
+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 declare function buildErrorLog(err: KumikoError): ErrorLogEntry;
+type CauseSnapshot = {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+    readonly cause?: CauseSnapshot;
+};
+export {};

package/dist/errors/serialize.js

@@ -0,0 +1,76 @@
+// 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 = () => process.env["NODE_ENV"] === "production";
+function devCauseDetail(cause) {
+    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, requestId) {
+    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(),
+        },
+    };
+}
+export function buildErrorLog(err) {
+    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) }),
+    };
+}
+const MAX_CAUSE_DEPTH = 10;
+function serializeCause(cause, depth = 0) {
+    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/dist/errors/to-kumiko-error.d.ts

@@ -0,0 +1,2 @@
+import { type KumikoError } from "./kumiko-error.js";
+export declare function toKumikoError(e: unknown): KumikoError;

package/dist/errors/to-kumiko-error.js

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

package/dist/errors/transition-details.d.ts

@@ -0,0 +1,7 @@
+export type InvalidTransitionDetails = {
+    readonly from: string;
+    readonly to: string;
+    readonly allowed: readonly string[];
+    readonly message: string;
+};
+export declare function buildInvalidTransitionDetails(from: string, to: string, allowed: readonly string[]): InvalidTransitionDetails;

package/dist/errors/transition-details.js

@@ -0,0 +1,16 @@
+// 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 function buildInvalidTransitionDetails(from, to, allowed) {
+    return {
+        from,
+        to,
+        allowed,
+        message: `Invalid transition: "${from}" → "${to}". Allowed from "${from}": ${allowed.length > 0 ? allowed.join(", ") : "none"}`,
+    };
+}

package/dist/errors/write-error-info.d.ts

@@ -0,0 +1,20 @@
+import type { WriteErrorInfo, WriteFailure } from "@cosmicdrift/kumiko-types/write-error-info-types";
+import { KumikoError } from "./kumiko-error.js";
+export type { WriteErrorInfo, WriteFailure };
+export declare function writeFailure(err: KumikoError): WriteFailure;
+export declare function failNotFound(entity: string, id?: number | string): WriteFailure;
+export declare function failUnprocessable(reason: string, details?: Readonly<Record<string, unknown>> & {
+    readonly reason?: never;
+}): WriteFailure;
+/**
+ * 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 declare function failTransition(from: string, to: string, allowed: readonly string[]): WriteFailure;
+export declare function toWriteErrorInfo(err: KumikoError): WriteErrorInfo;
+export declare function reraiseAsKumikoError(info: WriteErrorInfo): KumikoError;

package/dist/errors/write-error-info.js

@@ -0,0 +1,99 @@
+import { NotFoundError, UnprocessableError } from "./classes.js";
+import { KumikoError } from "./kumiko-error.js";
+import { FrameworkReasons } from "./reasons.js";
+import { buildInvalidTransitionDetails } from "./transition-details.js";
+// 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) {
+    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, id) {
+    return writeFailure(new NotFoundError(entity, id));
+}
+// @wrapper-known error-helper
+export function failUnprocessable(reason, details) {
+    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, to, allowed) {
+    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();
+export function toWriteErrorInfo(err) {
+    // 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 = {
+        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) {
+    return new ReraisedError(info, causeByWriteErrorInfo.get(info));
+}
+class ReraisedError extends KumikoError {
+    code;
+    httpStatus;
+    constructor(info, cause) {
+        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/dist/errors/zod-bridge.d.ts

@@ -0,0 +1,3 @@
+import type { ZodError } from "zod";
+import { ValidationError } from "./classes.js";
+export declare function validationErrorFromZod(error: ZodError): ValidationError;

package/dist/errors/zod-bridge.js

@@ -0,0 +1,58 @@
+import { ValidationError } from "./classes.js";
+// 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
+];
+export function validationErrorFromZod(error) {
+    const fields = error.issues.map((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) {
+    if (issue.code === "custom") {
+        const override = issue.params?.["i18nKey"];
+        if (typeof override === "string")
+            return override;
+    }
+    return `errors.validation.${issue.code}`;
+}
+function extractIssueParams(issue) {
+    // 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 = {};
+    const bag = issue; // @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/dist/es-ops/context.d.ts

@@ -0,0 +1,19 @@
+import type { DbRunner } from "../db/index.js";
+import type { Dispatcher } from "../pipeline/dispatcher.js";
+import type { SeedMigrationContext } from "./types.js";
+export type CreateSeedMigrationContextArgs = {
+    readonly dispatcher: Dispatcher;
+    readonly dbRunner: DbRunner;
+};
+/** Builder: gibt eine factory-function zurück die der Runner pro-Migration
+ *  aufruft. Der dbRunner kann eine Top-Connection oder eine Tx sein —
+ *  Read-Helpers nutzen ihn direkt, systemWriteAs delegiert an dispatcher.
+ *
+ *  Hinweis: dispatcher.write bekommt den Runner-tx NICHT durchgereicht —
+ *  runBatch öffnet eine eigene Transaktion auf context.db (eigene Pool-
+ *  Connection). Die Writes committen daher unabhängig: ein Runner-Failure
+ *  rollt NUR den Marker-Insert + dbRunner-reads zurück, die dispatcher-Writes
+ *  bleiben committed. Seeds MÜSSEN deshalb idempotent sein (verifiziert in
+ *  runner.integration.test.ts „dispatcher-writes vor throw bleiben committed"). */
+export declare function createSeedMigrationContext(args: CreateSeedMigrationContextArgs): SeedMigrationContext;
+export type { SeedMigrationContext } from "./types.js";

package/dist/es-ops/context.js

@@ -0,0 +1,70 @@
+// SeedMigrationContext-Builder. Caller (runProdApp/CLI) übergibt einen
+// schon-konfigurierten Dispatcher; der Builder produziert pro-Migration
+// einen tx-scoped Context der via dispatcher.write den existierenden
+// Handler-Pfad nutzt — gleiches Pattern wie ein User-UI-Click.
+//
+// SystemUser bypassed Access-Checks (Standard-Seed-Pattern, siehe
+// config-seed.ts:40). Events haben createdBy = SYSTEM_TENANT_ID-User
+// → audit-fähig.
+import { selectAllTenants, selectMembershipsOfUser, selectUserByEmail, } from "../db/queries/seed-context.js";
+import { createSystemUser, SYSTEM_TENANT_ID } from "../engine/index.js";
+import { parseStringArrayJson } from "../utils/parse-string-array-json.js";
+/** Builder: gibt eine factory-function zurück die der Runner pro-Migration
+ *  aufruft. Der dbRunner kann eine Top-Connection oder eine Tx sein —
+ *  Read-Helpers nutzen ihn direkt, systemWriteAs delegiert an dispatcher.
+ *
+ *  Hinweis: dispatcher.write bekommt den Runner-tx NICHT durchgereicht —
+ *  runBatch öffnet eine eigene Transaktion auf context.db (eigene Pool-
+ *  Connection). Die Writes committen daher unabhängig: ein Runner-Failure
+ *  rollt NUR den Marker-Insert + dbRunner-reads zurück, die dispatcher-Writes
+ *  bleiben committed. Seeds MÜSSEN deshalb idempotent sein (verifiziert in
+ *  runner.integration.test.ts „dispatcher-writes vor throw bleiben committed"). */
+export function createSeedMigrationContext(args) {
+    // Default-Executor für System-scope-Aggregates (config-values, system
+    // text-content, etc.). Bei Tenant-scope-Aggregates muss der Caller
+    // explizit `tenantIdOverride` übergeben — siehe types.ts Doku.
+    const defaultSystemUser = createSystemUser(SYSTEM_TENANT_ID);
+    return {
+        systemWriteAs: async (handlerQualifiedName, payload, tenantIdOverride, extraRoles) => {
+            // tenantIdOverride: baut einen System-User mit der Stream-tenantId
+            // damit der Event-Store-Executor das Aggregate im richtigen Stream
+            // findet. Verhindert die version_conflict-Falle (siehe Memory
+            // feedback_event_store_tenant_consistency.md).
+            const executor = tenantIdOverride !== undefined || (extraRoles && extraRoles.length > 0)
+                ? createSystemUser(tenantIdOverride ?? SYSTEM_TENANT_ID, extraRoles)
+                : defaultSystemUser;
+            const result = await args.dispatcher.write(handlerQualifiedName, payload, executor);
+            // Critical: WriteResult{isSuccess: false} würde sonst silent durchlaufen
+            // → Marker landet trotz failed-Write → Migration falsch als "applied"
+            // markiert. Hier throw damit der Runner's outer-tx rollback macht und
+            // Marker NICHT geschrieben wird. Seed-Author kann via try/catch eigene
+            // Fehler-Behandlung machen wenn ein soft-failure erwartet ist.
+            if (!result.isSuccess) {
+                const code = result.error?.code ?? "unknown";
+                const message = result.error?.message ?? "(no message)";
+                throw new Error(`[es-ops/seed-migration] systemWriteAs("${handlerQualifiedName}") failed: ${code} — ${message}`);
+            }
+            return result;
+        },
+        findUserByEmail: async (email) => {
+            const row = await selectUserByEmail(args.dbRunner, email);
+            if (!row)
+                return null;
+            return { id: row.id, email: row.email, tenantId: row.tenantId };
+        },
+        findMembershipsOfUser: async (userId) => {
+            const rows = await selectMembershipsOfUser(args.dbRunner, userId);
+            return rows.map((r) => ({
+                userId: r.user_id,
+                tenantId: r.tenant_id,
+                streamTenantId: r.stream_tenant_id,
+                roles: parseStringArrayJson(r.roles),
+            }));
+        },
+        findTenants: async () => {
+            const rows = await selectAllTenants(args.dbRunner);
+            return rows.map((r) => ({ id: r.id, name: r.name, tenantKey: r.tenant_key }));
+        },
+        db: args.dbRunner,
+    };
+}

package/dist/es-ops/index.d.ts

@@ -0,0 +1,4 @@
+export { type CreateSeedMigrationContextArgs, createSeedMigrationContext, } from "./context.js";
+export { createEsOperationsTable, type EsOperationAppliedBy, type EsOperationType, esOperationsTable, } from "./operations-schema.js";
+export { type RunPendingSeedMigrationsArgs, type RunPendingSeedMigrationsResult, runPendingSeedMigrations, } from "./runner.js";
+export type { SeedMembershipRow, SeedMigration, SeedMigrationContext, SeedTenantRow, SeedUserRow, } from "./types.js";

package/dist/es-ops/index.js

@@ -0,0 +1,14 @@
+// es-ops — ES-Operations-Pattern für Kumiko-Apps.
+//
+// Phase 1: seed-migrations. Phase 2+ docken an dieselbe Infra an
+// (kumiko_es_operations-Table mit operation_type-Discriminator).
+//
+// App-Author-API:
+//   - SeedMigration: default-export-Typ einer seed-file
+//   - runProdApp({ seedsDir }): Framework runs pending bei Boot
+//   - bunx kumiko ops seed:new|status|apply (CLI)
+//
+// Plan-Doc: kumiko-platform/docs/plans/features/es-ops.md
+export { createSeedMigrationContext, } from "./context.js";
+export { createEsOperationsTable, esOperationsTable, } from "./operations-schema.js";
+export { runPendingSeedMigrations, } from "./runner.js";

package/dist/es-ops/operations-schema.d.ts

@@ -0,0 +1,5 @@
+import { type DbConnection } from "../db/index.js";
+export type EsOperationType = "seed-migration";
+export type EsOperationAppliedBy = "boot" | "cli" | "ci-pipeline";
+export declare const esOperationsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare function createEsOperationsTable(db: DbConnection): Promise<void>;