@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/dist/env/index.js

@@ -0,0 +1,313 @@
+// Env-Schema composition for Kumiko apps.
+//
+// Each feature declares its required env-vars via `r.envSchema(z.object({...}))`.
+// `composeEnvSchema({ features, extend })` merges those into one app-wide
+// Zod-object that `runProdApp` validates `process.env` against at boot.
+//
+// On invalid/missing vars `parseEnv` throws `KumikoBootError` with ALL
+// problems aggregated (Zod's safeParse traverses every field before
+// short-circuiting). `runProdApp` catches at its top level and renders
+// via `KumikoBootError.format()` — so apps don't repeat the try/catch.
+//
+// Per-var metadata for deploy-time tooling (Pulumi-config-key override,
+// generator command, k8s hints) lives in Zod's `.meta({ kumiko: {...} })`.
+// Without meta, defaults: `camelCase(envVarName)` for the Pulumi key,
+// `<set-me>` placeholder for the value, no `--secret` flag.
+import * as z from "zod";
+import { zodDef, zodDescription, zodMeta, zodShape, zodShapeField } from "./_zod-introspect.js";
+function isKumikoMeta(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    // @cast-boundary schema-walk — runtime-shape narrowing of zod-meta payload
+    const v = value;
+    if (v.kms !== undefined && v.kms !== true)
+        return false;
+    if (v.pulumi === undefined)
+        return true;
+    if (v.pulumi === null || typeof v.pulumi !== "object")
+        return false;
+    // @cast-boundary schema-walk
+    const p = v.pulumi;
+    if (p.name !== undefined && typeof p.name !== "string")
+        return false;
+    if (p.generator !== undefined && typeof p.generator !== "string")
+        return false;
+    if (p.secret !== undefined && typeof p.secret !== "boolean")
+        return false;
+    return true;
+}
+export function readKumikoMeta(field) {
+    const meta = zodMeta(field);
+    if (meta && typeof meta === "object" && meta !== null && "kumiko" in meta) {
+        // @cast-boundary schema-walk
+        const k = meta.kumiko;
+        if (isKumikoMeta(k))
+            return k;
+    }
+    return {};
+}
+/** Env names whose schema field declares `kms: true` — the slots
+ *  `resolvePlatformKeks` resolves from a ciphertext. */
+export function kmsSlotsOf(schema) {
+    return Object.entries(zodShape(schema))
+        .filter(([, field]) => readKumikoMeta(field).kms === true)
+        .map(([name]) => name);
+}
+// A ciphertext-only slot is satisfied by its `_CIPHERTEXT` twin: the plaintext
+// only exists after the boot-time decrypt, so requiring it here would reject
+// exactly the deployment this meta enables. safeExtend, not extend: Zod 4 throws
+// on extend for schemas carrying refinements (app-level superRefine).
+function relaxCiphertextOnlySlots(schema, env) {
+    const shape = zodShape(schema);
+    const relaxed = {};
+    for (const name of kmsSlotsOf(schema)) {
+        const field = shape[name];
+        if (field && env[name] === undefined && env[`${name}_CIPHERTEXT`])
+            relaxed[name] = field.optional();
+    }
+    return Object.keys(relaxed).length === 0 ? schema : schema.safeExtend(relaxed);
+}
+export function classifyField(field) {
+    // Drill through ZodEffects/ZodPipe wrappers to find the inner kind.
+    let current = field;
+    for (let i = 0; i < 8; i++) {
+        if (current instanceof z.ZodDefault)
+            return "withDefault";
+        if (current instanceof z.ZodOptional || current instanceof z.ZodNullable) {
+            return "optional";
+        }
+        const inner = zodDef(current);
+        if (inner?.innerType) {
+            current = inner.innerType;
+            continue;
+        }
+        if (inner?.in) {
+            current = inner.in;
+            continue;
+        }
+        break;
+    }
+    return "required";
+}
+export function getDefaultValue(field) {
+    let current = field;
+    for (let i = 0; i < 8; i++) {
+        if (current instanceof z.ZodDefault) {
+            // Zod v4: defaultValue is the raw value (v3 was a factory function).
+            // Support both shapes for forward/backward safety.
+            const raw = zodDef(current)?.defaultValue;
+            // @cast-boundary schema-walk — Zod v3 stored a thunk, v4 a raw value
+            return typeof raw === "function" ? raw() : raw;
+        }
+        const inner = zodDef(current);
+        if (inner?.innerType) {
+            current = inner.innerType;
+            continue;
+        }
+        break;
+    }
+    return undefined;
+}
+// @wrapper-known semantic-alias
+export function getFieldDescription(field) {
+    return zodDescription(field);
+}
+// `.optional()` returns a new Zod instance that drops `.meta()`, which would
+// hide the slot from `kmsSlotsOf` on the composed schema.
+function optionalKeepingKmsMeta(field) {
+    const optional = field.optional();
+    return readKumikoMeta(field).kms === true
+        ? optional.meta({ kumiko: readKumikoMeta(field) })
+        : optional;
+}
+export function composeEnvSchema(options) {
+    const optionalSet = new Set(options.optionalFeatures ?? []);
+    const merged = {};
+    const sources = {};
+    const kmsFields = [];
+    const noteKms = (name, field, source) => {
+        if (readKumikoMeta(field).kms === true)
+            kmsFields.push({ name, source });
+    };
+    // Framework-core first so a feature that accidentally declares the same
+    // var (e.g. PORT) gets a clear conflict error citing "framework-core"
+    // rather than silently overwriting a deploy-critical default. The
+    // conflict-detection makes the order safe in both directions — both
+    // throw — but downstream tools that consume `sources` (e.g. the
+    // upcoming Phase-5 lint-guard) may rely on this insertion order.
+    if (options.core) {
+        for (const [key, field] of Object.entries(zodShape(options.core))) {
+            merged[key] = field;
+            sources[key] = "framework-core";
+            noteKms(key, field, "framework-core");
+        }
+    }
+    for (const feature of options.features) {
+        if (!feature.envSchema)
+            continue;
+        const shape = zodShape(feature.envSchema);
+        const wrap = optionalSet.has(feature.name);
+        for (const [key, field] of Object.entries(shape)) {
+            if (merged[key] !== undefined) {
+                throw new KumikoBootError([
+                    {
+                        name: key,
+                        kind: "invalid",
+                        message: `env-var conflict: "${key}" declared by both ` +
+                            `"${sources[key]}" and "${feature.name}" — pick one owner.`,
+                    },
+                ]);
+            }
+            merged[key] = wrap ? optionalKeepingKmsMeta(field) : field;
+            sources[key] = feature.name;
+            noteKms(key, field, feature.name);
+        }
+    }
+    if (options.extend) {
+        for (const [key, field] of Object.entries(zodShape(options.extend))) {
+            if (merged[key] !== undefined) {
+                throw new KumikoBootError([
+                    {
+                        name: key,
+                        kind: "invalid",
+                        message: `env-var conflict: "${key}" declared by both "${sources[key]}" ` +
+                            `and the app's extend block — rename one.`,
+                    },
+                ]);
+            }
+            merged[key] = field;
+            sources[key] = "app";
+            noteKms(key, field, "app");
+        }
+    }
+    // The twin follows from the slot, so a versioned family (`…_V2`) needs no
+    // second declaration. An already declared twin (apps that predate this) stays.
+    for (const { name, source } of kmsFields) {
+        const twin = `${name}_CIPHERTEXT`;
+        if (merged[twin] !== undefined)
+            continue;
+        merged[twin] = z
+            .string()
+            .min(1)
+            .optional()
+            .describe(`Key-Manager ciphertext of ${name}; used when ${name} is unset.`);
+        sources[twin] = source;
+    }
+    return {
+        schema: z.object(merged),
+        sources,
+    };
+}
+function formatBootError(errors) {
+    const lines = [
+        `Boot failed: ${errors.length} env-var problem${errors.length === 1 ? "" : "s"}`,
+        "",
+    ];
+    for (const err of errors) {
+        const tag = err.kind === "missing" ? "required, missing" : "invalid";
+        const sourceTag = err.source ? `${err.source}, ${tag}` : tag;
+        lines.push(`  ✗ ${err.name} (${sourceTag})`);
+        lines.push(`    ${err.message}`);
+        if (err.suggestion) {
+            lines.push(`    ${err.suggestion}`);
+        }
+    }
+    lines.push("");
+    lines.push("See: kumiko-platform/docs/runbooks/standard-deploy-app.md#step-1-boot-dry-run-lokal");
+    return lines.join("\n");
+}
+export class KumikoBootError extends Error {
+    errors;
+    constructor(errors) {
+        super(formatBootError(errors));
+        this.name = "KumikoBootError";
+        this.errors = errors;
+    }
+    format() {
+        return formatBootError(this.errors);
+    }
+}
+export function parseEnv(schema, env, options = {}) {
+    // Filter undefined values to keep Zod's required-vs-invalid signal clean.
+    // (process.env returns string|undefined; passing undefined would parse
+    // as "field is set to undefined" which clouds the missing-key heuristic.)
+    const cleaned = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (v !== undefined)
+            cleaned[k] = v;
+    }
+    const result = relaxCiphertextOnlySlots(schema, cleaned).safeParse(cleaned);
+    if (result.success) {
+        // @cast-boundary schema-walk — z.infer<S> erasure across safeParse result
+        return result.data;
+    }
+    // Map Zod-issues → EnvError[], augmenting with suggestions when meta+prefix.
+    const errors = result.error.issues.map((issue) => {
+        const name = String(issue.path[0] ?? "<unknown>");
+        const field = zodShapeField(schema, name);
+        // Zod v4 dropped the `received` property on invalid_type issues; the
+        // canonical signal for "value was missing" is now "the key isn't in
+        // the input object". Use input-presence as the missing/invalid switch.
+        const isMissing = issue.code === "invalid_type" && !(name in cleaned);
+        const kind = isMissing ? "missing" : "invalid";
+        const desc = field ? getFieldDescription(field) : undefined;
+        const message = desc ? `${issue.message} — ${desc}` : issue.message;
+        const suggestion = field ? buildPulumiSuggestion(name, field, options.pulumiPrefix) : undefined;
+        const source = options.sources?.[name];
+        return {
+            name,
+            kind,
+            message,
+            ...(source ? { source } : {}),
+            ...(suggestion ? { suggestion } : {}),
+        };
+    });
+    throw new KumikoBootError(errors);
+}
+// --- Pulumi-suggestion ---
+function ucfirst(s) {
+    return s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
+}
+/** Dry-Run-Gegenstück zu parseEnv (KUMIKO_DRY_RUN_ENV-Pfad): parst jedes
+ *  Feld einzeln und liefert ein ehrliches Partial — vorhandene Werte kommen
+ *  typisiert (gecoerct) durch, fehlende/invalide fehlen einfach. Wirft nie:
+ *  der Dry-Run soll das Inventory rendern, nicht an required-Feldern
+ *  scheitern. Ersetzt das `({} as Shape)`-Muster, bei dem JEDER Zugriff
+ *  silent undefined war und das Compile-Level nichts davon wusste. */
+export function parseEnvDryRun(schema, env) {
+    const out = {};
+    for (const [name, field] of Object.entries(zodShape(schema))) {
+        const raw = env[name];
+        if (raw === undefined)
+            continue;
+        const result = field.safeParse(raw);
+        if (result.success)
+            out[name] = result.data;
+    }
+    // @cast-boundary schema-walk — Partial<z.infer<S>> erasure über den
+    // per-Feld-safeParse; jeder enthaltene Wert hat seinen Feld-Parse bestanden.
+    return out;
+}
+export function camelCase(snakeShout) {
+    const parts = snakeShout.toLowerCase().split("_").filter(Boolean);
+    if (parts.length === 0)
+        return snakeShout.toLowerCase();
+    return parts[0] + parts.slice(1).map(ucfirst).join("");
+}
+export function pulumiConfigKey(envName, field, prefix) {
+    const meta = field ? readKumikoMeta(field) : {};
+    if (meta.pulumi?.name) {
+        return prefix ? prefix + ucfirst(meta.pulumi.name) : meta.pulumi.name;
+    }
+    const camel = camelCase(envName);
+    return prefix ? prefix + ucfirst(camel) : camel;
+}
+export function buildPulumiSuggestion(envName, field, prefix) {
+    if (!prefix)
+        return undefined;
+    const meta = readKumikoMeta(field);
+    const key = pulumiConfigKey(envName, field, prefix);
+    const secretFlag = meta.pulumi?.secret ? " --secret" : "";
+    const value = meta.pulumi?.generator ? `"$(${meta.pulumi.generator})"` : `"<set-me>"`;
+    return `Set via: pulumi config set${secretFlag} ${key} ${value}`;
+}

package/dist/errors/classes.d.ts

@@ -0,0 +1,109 @@
+import type { FieldIssue } from "./field-issue.js";
+import { type ErrorOpts, KumikoError } from "./kumiko-error.js";
+export type { FieldIssue } from "./field-issue.js";
+export type ValidationDetails = {
+    readonly fields: readonly FieldIssue[];
+};
+export declare class ValidationError extends KumikoError {
+    readonly code = "validation_error";
+    readonly httpStatus = 400;
+    constructor(details: ValidationDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
+}
+export type FeatureDisabledDetails = {
+    readonly reason: "feature_disabled";
+    readonly feature: string;
+    readonly handler: string;
+};
+export declare class FeatureDisabledError extends KumikoError {
+    readonly code = "feature_disabled";
+    readonly httpStatus = 403;
+    constructor(feature: string, handler: string, opts?: Pick<ErrorOpts, "cause">);
+}
+export declare class AccessDeniedError extends KumikoError {
+    readonly code = "access_denied";
+    readonly httpStatus = 403;
+    constructor(opts?: Pick<ErrorOpts, "message" | "i18nKey" | "i18nParams" | "details" | "cause">);
+}
+export type NotFoundDetails = {
+    readonly entity: string;
+    readonly id?: string;
+};
+export declare class NotFoundError extends KumikoError {
+    readonly code = "not_found";
+    readonly httpStatus = 404;
+    constructor(entity: string, id?: string | number, opts?: Pick<ErrorOpts, "i18nKey" | "i18nParams" | "cause">);
+}
+export declare class ConflictError extends KumikoError {
+    readonly code: string;
+    readonly httpStatus = 409;
+    constructor(opts?: Pick<ErrorOpts, "message" | "i18nKey" | "i18nParams" | "details" | "cause">);
+}
+export type VersionConflictDetails = {
+    readonly entityId: number | string;
+    readonly expectedVersion: number;
+    readonly currentVersion: number;
+};
+export declare class VersionConflictError extends ConflictError {
+    readonly code: string;
+    constructor(details: VersionConflictDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
+}
+export type PreconditionFailedDetails = {
+    readonly entityId: number | string;
+    readonly field: string;
+};
+export declare class PreconditionFailedError extends ConflictError {
+    readonly code: string;
+    constructor(details: PreconditionFailedDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
+}
+export declare class IdempotentReplayError extends ConflictError {
+    readonly code: string;
+    constructor(details: {
+        readonly idempotencyKey: string;
+    }, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
+}
+export type UniqueViolationDetails = {
+    readonly entityName: string;
+    readonly constraintName?: string;
+};
+export declare class UniqueViolationError extends ConflictError {
+    readonly code: string;
+    constructor(details: UniqueViolationDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
+}
+export type UnprocessableOpts = Pick<ErrorOpts, "i18nKey" | "i18nParams" | "cause" | "message"> & {
+    readonly details?: Readonly<Record<string, unknown>> & {
+        readonly reason?: never;
+    };
+};
+export declare class UnprocessableError extends KumikoError {
+    readonly code: string;
+    readonly httpStatus = 422;
+    constructor(reason: string, opts?: UnprocessableOpts);
+}
+export type UnconfiguredDetails = {
+    readonly feature: string;
+    readonly key: string;
+    readonly hint?: string;
+};
+export declare class UnconfiguredError extends UnprocessableError {
+    readonly code: string;
+    constructor(details: UnconfiguredDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
+}
+export declare class InternalError extends KumikoError {
+    readonly code = "internal_error";
+    readonly httpStatus = 500;
+    constructor(opts?: Pick<ErrorOpts, "message" | "i18nKey" | "i18nParams" | "details" | "cause">);
+}
+export type RateLimitDetails = {
+    readonly bucket: string;
+    readonly limit: number;
+    readonly windowSeconds: number;
+    readonly remaining: number;
+    readonly retryAfterSeconds: number;
+    readonly resetAt: string;
+};
+export declare class RateLimitError extends KumikoError {
+    readonly code = "rate_limited";
+    readonly httpStatus = 429;
+    readonly details: RateLimitDetails;
+    constructor(details: RateLimitDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">);
+}

package/dist/errors/classes.js

@@ -0,0 +1,190 @@
+import { toSnakeCase } from "../utils/case.js";
+import { KumikoError } from "./kumiko-error.js";
+export class ValidationError extends KumikoError {
+    code = "validation_error";
+    httpStatus = 400;
+    constructor(details, opts) {
+        // The wire `message` stays a short human-readable fallback — Zod's own
+        // `error.message` is a multi-line JSON blob that would look awful in any
+        // UI. Per-field details belong in `details.fields` (structured, i18nable);
+        // the full ZodError is preserved in `cause` for forensics in the log.
+        super({
+            message: "Validation failed",
+            i18nKey: opts?.i18nKey ?? "errors.validation.failed",
+            details,
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+    }
+}
+export class FeatureDisabledError extends KumikoError {
+    code = "feature_disabled";
+    httpStatus = 403;
+    constructor(feature, handler, opts) {
+        super({
+            message: `feature ${feature} is disabled`,
+            i18nKey: "errors.feature.disabled",
+            i18nParams: { feature },
+            details: { reason: "feature_disabled", feature, handler },
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+    }
+}
+export class AccessDeniedError extends KumikoError {
+    code = "access_denied";
+    httpStatus = 403;
+    constructor(opts) {
+        super({
+            message: opts?.message ?? "access denied",
+            i18nKey: opts?.i18nKey ?? "errors.access.denied",
+            ...(opts?.i18nParams && { i18nParams: opts.i18nParams }),
+            ...(opts?.details !== undefined && { details: opts.details }),
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+    }
+}
+export class NotFoundError extends KumikoError {
+    code = "not_found";
+    httpStatus = 404;
+    constructor(entity, id, opts) {
+        const idStr = id !== undefined ? String(id) : undefined;
+        // The reason string follows `<snake_entity>_not_found` — keeps a stable,
+        // client-friendly tag that survives wire serialization even if the entity
+        // name is later renamed for display purposes. Strip the leading underscore
+        // toSnakeCase emits for a PascalCase name ("Invoice" → "_invoice") so the
+        // wire tag stays "invoice_not_found", not "_invoice_not_found".
+        const reason = `${toSnakeCase(entity).replace(/^_/, "")}_not_found`;
+        const details = { reason, entity, id: idStr };
+        super({
+            message: idStr !== undefined ? `${entity} ${idStr} not found` : `${entity} not found`,
+            i18nKey: opts?.i18nKey ?? "errors.notFound",
+            i18nParams: { entity, id: idStr, ...opts?.i18nParams },
+            details,
+            cause: opts?.cause,
+        });
+    }
+}
+// Generic 409. Features that need a narrower shape should subclass (see
+// VersionConflictError) — this way the HTTP layer stays uniform while callers
+// can still instanceof on the concrete subtype in handlers.
+export class ConflictError extends KumikoError {
+    // Widened to `string` so subclasses (VersionConflictError) can refine the
+    // value without TS blocking the override. The base class still enforces
+    // "some code is set"; concrete classes pick their own literal.
+    code = "conflict";
+    httpStatus = 409;
+    constructor(opts) {
+        super({
+            message: opts?.message ?? "conflict",
+            i18nKey: opts?.i18nKey ?? "errors.conflict",
+            ...(opts?.i18nParams && { i18nParams: opts.i18nParams }),
+            ...(opts?.details !== undefined && { details: opts.details }),
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+    }
+}
+export class VersionConflictError extends ConflictError {
+    code = "version_conflict";
+    constructor(details, opts) {
+        super({
+            message: `version conflict for entity ${details.entityId}`,
+            i18nKey: opts?.i18nKey ?? "errors.versionConflict",
+            details,
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+    }
+}
+export class PreconditionFailedError extends ConflictError {
+    code = "precondition_failed";
+    constructor(details, opts) {
+        super({
+            message: `precondition failed for entity ${details.entityId}: field "${details.field}" no longer matches the expected value`,
+            i18nKey: opts?.i18nKey ?? "errors.preconditionFailed",
+            details,
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+    }
+}
+// The caller retried a write with an idempotencyKey it had already used —
+// the event-store's partial unique index on metadata.idempotencyKey caught
+// the duplicate. Distinct from unique_violation/version_conflict: this is
+// not an error the caller should retry, it means the earlier attempt
+// already succeeded and this one is a no-op replay.
+export class IdempotentReplayError extends ConflictError {
+    code = "idempotent_replay";
+    constructor(details, opts) {
+        super({
+            message: `event with idempotencyKey "${details.idempotencyKey}" was already appended`,
+            i18nKey: opts?.i18nKey ?? "errors.idempotentReplay",
+            details,
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+    }
+}
+export class UniqueViolationError extends ConflictError {
+    code = "unique_violation";
+    constructor(details, opts) {
+        super({
+            message: `unique constraint violated on entity ${details.entityName}${details.constraintName ? ` (${details.constraintName})` : ""}`,
+            i18nKey: opts?.i18nKey ?? "errors.uniqueViolation",
+            details,
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+    }
+}
+export class UnprocessableError extends KumikoError {
+    // Widened to `string` so subclasses (UnconfiguredError) can refine the
+    // value — same pattern as ConflictError above.
+    code = "unprocessable";
+    httpStatus = 422;
+    constructor(reason, opts) {
+        super({
+            message: opts?.message ?? `unprocessable: ${reason}`,
+            i18nKey: opts?.i18nKey ?? "errors.unprocessable",
+            ...(opts?.i18nParams && { i18nParams: opts.i18nParams }),
+            details: { ...opts?.details, reason },
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+    }
+}
+export class UnconfiguredError extends UnprocessableError {
+    code = "unconfigured";
+    constructor(details, opts) {
+        const message = `${details.feature}: '${details.key}' is empty — tenant must configure it before use.${details.hint ? ` ${details.hint}` : ""}`;
+        // Stable slug for docsUrl — freestext is the Error.message + details.message.
+        super("unconfigured", {
+            message,
+            i18nKey: opts?.i18nKey ?? "errors.unconfigured",
+            details: { ...details, message },
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+    }
+}
+// Auto-wrap target for unexpected throws. Never exposes .details to the client
+// — the serializer drops it. Stack + cause live in the log only.
+export class InternalError extends KumikoError {
+    code = "internal_error";
+    httpStatus = 500;
+    constructor(opts) {
+        super({
+            message: opts?.message ?? "internal error",
+            i18nKey: opts?.i18nKey ?? "errors.internal",
+            ...(opts?.i18nParams !== undefined && { i18nParams: opts.i18nParams }),
+            ...(opts?.details !== undefined && { details: opts.details }),
+            ...(opts?.cause !== undefined && { cause: opts.cause }),
+        });
+    }
+}
+export class RateLimitError extends KumikoError {
+    code = "rate_limited";
+    httpStatus = 429;
+    details;
+    constructor(details, opts) {
+        super({
+            message: `rate limited: ${details.bucket} (limit ${details.limit} per ${details.windowSeconds}s)`,
+            i18nKey: opts?.i18nKey ?? "errors.rate_limited",
+            details,
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+        this.details = details;
+    }
+}

package/dist/errors/field-issue.d.ts

@@ -0,0 +1,6 @@
+export type FieldIssue = {
+    readonly path: string;
+    readonly code: string;
+    readonly i18nKey: string;
+    readonly params?: Readonly<Record<string, unknown>>;
+};

package/dist/errors/field-issue.js

@@ -0,0 +1 @@
+export {};

package/dist/errors/index.d.ts

@@ -0,0 +1,15 @@
+export type { FeatureDisabledDetails, FieldIssue, NotFoundDetails, PreconditionFailedDetails, RateLimitDetails, UnconfiguredDetails, UniqueViolationDetails, UnprocessableOpts, ValidationDetails, VersionConflictDetails, } from "./classes.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export type { ErrorCtorInput, ErrorOpts } from "./kumiko-error.js";
+export { isKumikoError, KumikoError } from "./kumiko-error.js";
+export { memberResolutionReadOnlyDenied } from "./member-resolution.js";
+export type { AgentReason, FrameworkReason } from "./reasons.js";
+export { AgentReasons, FrameworkReasons } from "./reasons.js";
+export type { ErrorLogEntry, ErrorResponseBody } from "./serialize.js";
+export { buildErrorLog, serializeError } from "./serialize.js";
+export { toKumikoError } from "./to-kumiko-error.js";
+export type { InvalidTransitionDetails } from "./transition-details.js";
+export { buildInvalidTransitionDetails } from "./transition-details.js";
+export type { WriteErrorInfo, WriteFailure } from "./write-error-info.js";
+export { failNotFound, failTransition, failUnprocessable, reraiseAsKumikoError, toWriteErrorInfo, writeFailure, } from "./write-error-info.js";
+export { validationErrorFromZod } from "./zod-bridge.js";

package/dist/errors/index.js

@@ -0,0 +1,9 @@
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { isKumikoError, KumikoError } from "./kumiko-error.js";
+export { memberResolutionReadOnlyDenied } from "./member-resolution.js";
+export { AgentReasons, FrameworkReasons } from "./reasons.js";
+export { buildErrorLog, serializeError } from "./serialize.js";
+export { toKumikoError } from "./to-kumiko-error.js";
+export { buildInvalidTransitionDetails } from "./transition-details.js";
+export { failNotFound, failTransition, failUnprocessable, reraiseAsKumikoError, toWriteErrorInfo, writeFailure, } from "./write-error-info.js";
+export { validationErrorFromZod } from "./zod-bridge.js";

package/dist/errors/kumiko-error.d.ts

@@ -0,0 +1,25 @@
+export type ErrorOpts = {
+    readonly message?: string;
+    readonly i18nKey?: string;
+    readonly i18nParams?: Readonly<Record<string, unknown>>;
+    readonly details?: unknown;
+    readonly cause?: Error;
+};
+export type ErrorCtorInput = {
+    readonly message: string;
+    readonly i18nKey: string;
+    readonly i18nParams?: Readonly<Record<string, unknown>>;
+    readonly details?: unknown;
+    readonly cause?: Error;
+};
+export declare abstract class KumikoError extends Error {
+    abstract readonly code: string;
+    abstract readonly httpStatus: number;
+    readonly i18nKey: string;
+    readonly i18nParams: Readonly<Record<string, unknown>> | undefined;
+    readonly details: unknown;
+    constructor(input: ErrorCtorInput);
+    get docsUrl(): string;
+    private get reasonSlug();
+}
+export declare function isKumikoError(e: unknown): e is KumikoError;