@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/src/errors/i18n/de.yaml

@@ -1,244 +0,0 @@
-# i18n-Texte für die Reason-Kataloge aus reasons.ts (deutsch).
-#
-# Schema pro Reason-Key — der Key ist wörtlich der Reason-Wert, Punkte
-# inklusive: FrameworkReasons bleibt präfixfrei (`stale_state`), AgentReasons
-# behält seinen Namespace innerhalb eines flachen Keys
-# (`agent.tool_not_allowed`), nie als verschachtelte `agent:`-Map:
-#
-#   <reason_key>:
-#     endUser: |
-#       Was der End-User in der App-UI sieht.
-#       Verständliche Sprache, Handlungs-Aufforderung wenn anwendbar.
-#     developer: |
-#       Technischer Hintergrund + Hinweise zum Konfigurieren / Verhindern.
-#       Für App-Owner und Designer-Nutzer.
-
-stale_state:
-  endUser: |
-    Jemand anderes hat dieses Element zwischenzeitlich geändert.
-    Bitte Seite neu laden und nochmal speichern.
-  developer: |
-    `ConflictError` tritt auf wenn ein atomic UPDATE den Optimistic-Locking-
-    Race verloren hat — ein anderer Writer hat die Row zwischen Snapshot
-    und WHERE-Clause bewegt.
-
-    Standard-Verhalten im Client-SDK: Toast mit "Bitte neu laden" anzeigen
-    und Entity neu fetchen.
-
-    Wenn du Conflict-Handling pro Entity anpassen willst, siehe
-    [Optimistic-Locking-Konfiguration](/en/concepts/commands/).
-
-invalid_transition:
-  endUser: |
-    Diese Aktion ist im aktuellen Status nicht möglich.
-    Der Datensatz muss sich in einem bestimmten Zustand befinden,
-    damit dieser Schritt erlaubt ist.
-  developer: |
-    `UnprocessableError` beim `guardTransition`: ein State-Machine-Übergang
-    wurde abgelehnt weil der aktuelle Zustand nicht zu den erlaubten
-    Quell-Zuständen gehört.
-
-    `details.from`, `details.to` und `details.validTargets` enthalten die
-    Diagnose. Definiere erlaubte Übergänge in
-    `r.entity({ stateMachine: ... })`,
-    oder prüfe vor dem Aufruf den aktuellen Zustand.
-
-field_access_denied:
-  endUser: |
-    Du darfst dieses Feld nicht ändern.
-    Wende dich an einen Administrator wenn du diese Berechtigung brauchst.
-  developer: |
-    `AccessDeniedError` beim Field-Level-Write-Check des Dispatchers: ein
-    Schreibversuch auf ein Feld wurde abgelehnt weil die aktuelle Rolle
-    keinen Zugriff hat.
-
-    `details.field` und `details.handler` enthalten die Diagnose.
-    Konfiguriere Field-Access in der Entity-Definition
-    (siehe [Permissions](/en/guides/field-level-permissions/)) oder fordere die
-    nötige Rolle an.
-
-delete_restricted:
-  endUser: |
-    Dieser Eintrag kann nicht gelöscht werden weil andere Datensätze noch
-    darauf verweisen.
-    Lösche zuerst die abhängigen Einträge.
-  developer: |
-    `ConflictError` beim Cascade-Delete-Guard: das Löschen wurde verhindert
-    weil dependent Rows existieren.
-
-    `details.blockingEntity`, `details.entity` und `details.entityId` zeigen
-    welche Relation blockiert. Setze `relation.onDelete` auf `"cascade"`
-    oder `"setNull"` wenn automatisches Aufräumen gewünscht ist, oder lösche
-    die abhängigen Rows zuerst.
-
-feature_disabled:
-  endUser: |
-    Diese Funktion ist aktuell nicht verfügbar.
-    Versuche es später noch einmal oder kontaktiere den Administrator.
-  developer: |
-    `FeatureDisabledError`: das Feature des aufgerufenen Handlers wurde
-    global deaktiviert. Distinct von `access_denied` — Clients sollten
-    "Funktion gerade nicht verfügbar" zeigen, nicht "keine Berechtigung".
-
-    `details.feature` und `details.handler` zeigen welches Feature/Handler.
-    Aktiviere das Feature via Feature-Toggle oder Routing-Config (siehe
-    [Feature-Toggles](/en/feature-reference/feature-toggles/)).
-
-system_identity_switch_denied:
-  endUser: |
-    Diese Aktion ist nicht erlaubt.
-    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
-  developer: |
-    `AccessDeniedError`: ein Handler oder Hook hat `ctx.queryAs`/`ctx.writeAs`
-    mit einer SYSTEM-Identität aufgerufen, ohne `r.systemScope()`-Handler, Job
-    zu sein oder `escapeHatch: { reason }` zu deklarieren.
-
-    Deklariere `escapeHatch: { reason: "..." }` am Write- oder Query-Handler
-    (oder am `r.hook(...)`-Aufruf, wenn der Wechsel in einem Hook passiert),
-    oder verlagere die Logik in ein `r.systemScope()`-Feature oder einen Job.
-
-identity_switch_denied:
-  endUser: |
-    Diese Aktion ist nicht erlaubt.
-    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
-  developer: |
-    `AccessDeniedError`: ein Handler oder Hook hat `ctx.queryAs`/`ctx.writeAs`
-    mit einer anderen Identität als dem eigenen Caller aufgerufen — andere
-    User-ID, anderer Tenant, andere Claims oder Origin, oder Rollen, die der
-    Caller nicht hat — ohne `r.systemScope()`-Handler, Job zu sein oder
-    `escapeHatch: { reason }` zu deklarieren. Der Wechsel auf den Caller selbst
-    oder eine Teilmenge seiner Rollen bleibt frei.
-
-    Deklariere `escapeHatch: { reason: "..." }` am Write- oder Query-Handler
-    (oder am `r.hook(...)`-Aufruf, wenn der Wechsel in einem Hook passiert),
-    oder verlagere die Logik in ein `r.systemScope()`-Feature oder einen Job.
-
-unsafe_all_tenants_denied:
-  endUser: |
-    Diese Aktion ist nicht erlaubt.
-    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
-  developer: |
-    `AccessDeniedError`: ein Handler oder Hook hat
-    `ctx.queryProjection(qualifiedName, { unsafeAllTenants: true })`
-    aufgerufen, ohne `r.systemScope()`-Handler zu sein oder
-    `escapeHatch: { reason }` zu deklarieren.
-
-    Deklariere `escapeHatch: { reason: "..." }` am Write-, Query- oder
-    Stream-Handler (oder am `r.hook(...)`-Aufruf, wenn der Read in einem Hook
-    passiert), oder verlagere die Logik in ein `r.systemScope()`-Feature.
-
-member_resolution_denied:
-  endUser: |
-    Diese Aktion ist nicht erlaubt.
-    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
-  developer: |
-    `AccessDeniedError`: `ctx.queryAsMember(userId, ...)` konnte für `userId`
-    keine aktive Mitgliedschaft im Tenant des Aufrufers auflösen (kein
-    Mitglied, Principal gesperrt, oder der Tenant befindet sich im Teardown).
-    Bewusst generisch — `details` verrät nie, welche Prüfung fehlgeschlagen ist.
-
-member_resolution_read_only:
-  endUser: |
-    Diese Aktion ist nicht erlaubt.
-    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
-  developer: |
-    `AccessDeniedError`: ein über `ctx.queryAsMember` erreichter Query-Handler
-    hat versucht zu schreiben (`ctx.write`/`writeAs`/`appendEvent`/
-    `jobRunner`/...). Aufgelöste Member-Principals sind nur lesend — es gibt
-    kein `writeAsMember`.
-
-public_intake_required:
-  endUser: |
-    Diese Aktion ist nicht erlaubt.
-    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
-  developer: |
-    `AccessDeniedError`: ein Write unter einem anonymen Wurzel-Handler hat ein
-    Personendaten-Feld (`pii` / `userOwned` / `recordOwned`) geschrieben, direkt
-    oder über `ctx.write`/`writeAs`/`queryAs` oder einen Hook. `details` nennen
-    `rootHandler`, `target` und `fields`. Ist der anonyme Intake gewollt, am
-    Wurzel-Handler `access: { roles: [..., "anonymous"], personalData: "public-intake" }`
-    deklarieren.
-
-irreversible_operation_requires_high_risk:
-  endUser: |
-    Diese Aktion ist nicht erlaubt.
-    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
-  developer: |
-    `AccessDeniedError`: der direkt aufgerufene Einstiegs-Handler führt ein
-    hartes Delete oder `forget` aus (`details.operation`), aber sein
-    aufgelöstes Agent-Risiko (`details.resolvedRisk`) liegt unter `"high"`.
-    `details.handler` nennt den Einstiegs-Handler — eine Delegation über
-    `ctx.write`/`writeAs` aus einem Handler mit niedrigerem Risiko erbt das
-    deklarierte Risiko des inneren Handlers nicht.
-
-    `agent: { risk: "high" }` am genannten Handler deklarieren.
-
-instruction_field_write_requires_high_risk:
-  endUser: |
-    Diese Aktion ist nicht erlaubt.
-    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
-  developer: |
-    `AccessDeniedError`: der direkt aufgerufene Einstiegs-Handler schreibt ein
-    Feld mit `readAsInstruction: true` (`details.fields`), aber sein
-    aufgelöstes Agent-Risiko (`details.resolvedRisk`) liegt unter `"high"`.
-    `details.handler` nennt den Einstiegs-Handler — eine Delegation über
-    `ctx.write`/`writeAs` aus einem Handler mit niedrigerem Risiko erbt das
-    deklarierte Risiko des inneren Handlers nicht.
-
-    `agent: { risk: "high" }` am genannten Handler deklarieren.
-
-agent.tool_not_allowed:
-  endUser: |
-    Dieses Tool ist im aktuellen Modus nicht verfügbar.
-    Stell den Assistenten auf einen Modus um, der diese Aktion abdeckt, oder
-    führe sie selbst in der App aus.
-  developer: |
-    `AccessDeniedError` aus dem Tool-Dispatch des Agenten: das Modell hat einen
-    Tool-Namen außerhalb des für diesen Lauf gebauten Katalogs angefragt — ein
-    halluzinierter Name, oder ein Handler, den der aktuelle Agent-Modus nicht
-    freigibt.
-
-    Der Katalog wird aus der gemounteten Registry abgeleitet
-    (`buildToolCatalog`) — ein Handler ohne `description` wird also gar nicht
-    erst zum Tool. Handler beschreiben oder den Agent-Modus weiten, wenn der
-    Call funktionieren sollte.
-
-agent.iteration_limit:
-  endUser: |
-    Der Assistent hat die maximale Anzahl an Schritten erreicht, ohne eine
-    eindeutige Antwort zu finden.
-    Bitte formuliere die Anfrage um oder teile sie in kleinere Schritte.
-  developer: |
-    `UnprocessableError` aus der Agent-Loop: der Lauf hat sein Runden-Limit
-    erreicht, bevor das Modell eine Endantwort produziert hat — meist ein Tool,
-    das immer wieder denselben Fehler liefert, oder eine Aufgabe, die mehr
-    Schritte braucht als das Limit erlaubt.
-
-    Runden-Limit für den Lauf anheben oder die Aufgabe verkleinern. Die
-    Turn-Historie der Unterhaltung zeigt, welcher Tool-Call sich wiederholt hat.
-
-agent.permission_denied:
-  endUser: |
-    Dir fehlt die Berechtigung für diese Aktion.
-    Der Assistent darf nur das, was dein eigener Account darf.
-  developer: |
-    `AccessDeniedError` aus dem Tool-Dispatch des Agenten: das Tool steht im
-    Katalog, aber die Rollen des Aufrufers decken den dahinterliegenden Handler
-    nicht ab. Der Agent läuft strikt mit den Rechten des aufrufenden Users — er
-    eskaliert nie.
-
-    Rolle am Handler ergänzen, oder hinnehmen, dass dieses Tool für diesen User
-    nicht verfügbar ist.
-
-agent.high_risk_no_always:
-  endUser: |
-    Für risikoreiche Aktionen kann „immer erlauben“ nicht gesetzt werden.
-    Jeder Lauf dieser Aktion braucht deine ausdrückliche Bestätigung.
-  developer: |
-    `AccessDeniedError` aus dem Risiko-Gate des Agenten: ein Handler mit
-    `agent: { risk: "high" }` wurde ohne die ausdrückliche Einzel-Bestätigung
-    aufgerufen, die solche Handler verlangen, oder es sollte eine
-    „immer erlauben“-Regel dafür gesetzt werden.
-
-    Deklariertes Risiko senken, wenn die Aktion wirklich Routine ist —
-    ansonsten ist der Bestätigungsdialog genau das gewollte Verhalten.

package/src/errors/i18n/en.yaml

@@ -1,234 +0,0 @@
-# i18n texts for the reason catalogs in reasons.ts (english).
-#
-# Schema per reason key — the key is the reason value verbatim, dots
-# included: FrameworkReasons stays prefix-free (`stale_state`), AgentReasons
-# keeps its namespace inside a flat key (`agent.tool_not_allowed`), never a
-# nested `agent:` map:
-#
-#   <reason_key>:
-#     endUser: |
-#       What the end-user sees in the app UI.
-#       Plain language, call-to-action where applicable.
-#     developer: |
-#       Technical background + hints on how to configure / prevent.
-#       For app owners and designer users.
-
-stale_state:
-  endUser: |
-    Someone else modified this item in the meantime.
-    Please reload the page and try saving again.
-  developer: |
-    `ConflictError` fires when an atomic UPDATE lost the optimistic-
-    locking race — another writer moved the row between our snapshot and
-    our WHERE clause.
-
-    Default client SDK behavior: toast a "please reload" message and
-    re-fetch the entity.
-
-    To customize conflict handling per entity, see
-    [optimistic locking configuration](/en/concepts/commands/).
-
-invalid_transition:
-  endUser: |
-    This action isn't allowed in the current state.
-    The record needs to be in a specific status before this step can happen.
-  developer: |
-    `UnprocessableError` from `guardTransition`: a state-machine transition
-    was rejected because the current state isn't in the allowed source
-    states.
-
-    `details.from`, `details.to` and `details.validTargets` carry the
-    diagnostics. Define allowed transitions in
-    `r.entity({ stateMachine: ... })`,
-    or check the current state before calling.
-
-field_access_denied:
-  endUser: |
-    You don't have permission to edit this field.
-    Please contact an administrator if you need this access.
-  developer: |
-    `AccessDeniedError` from the dispatcher's field-level write check: a
-    write to a field was rejected because the current role lacks access.
-
-    `details.field` and `details.handler` contain the diagnostics.
-    Configure field-level access in the entity definition (see
-    [Permissions](/en/guides/field-level-permissions/)) or request the required
-    role.
-
-delete_restricted:
-  endUser: |
-    This entry can't be deleted because other records still reference it.
-    Delete the dependent entries first.
-  developer: |
-    `ConflictError` from the cascade-delete guard: the delete was prevented
-    because dependent rows exist.
-
-    `details.blockingEntity`, `details.entity` and `details.entityId` show
-    which relation is blocking. Set `relation.onDelete` to `"cascade"` or
-    `"setNull"` if automatic cleanup is desired, or delete the dependent
-    rows first.
-
-feature_disabled:
-  endUser: |
-    This feature is currently unavailable.
-    Please try again later or contact an administrator.
-  developer: |
-    `FeatureDisabledError`: the feature owning the called handler is
-    globally disabled. Distinct from `access_denied` — clients should show
-    "feature currently unavailable" rather than "no permission".
-
-    `details.feature` and `details.handler` indicate which feature and
-    handler. Enable the feature via feature toggle or routing config (see
-    [Feature Toggles](/en/feature-reference/feature-toggles/)).
-
-system_identity_switch_denied:
-  endUser: |
-    This action isn't allowed.
-    Please contact an administrator if you believe this is a mistake.
-  developer: |
-    `AccessDeniedError`: a handler or hook called `ctx.queryAs`/`ctx.writeAs`
-    with a SYSTEM identity without being an `r.systemScope()` handler, a job,
-    or declaring `escapeHatch: { reason }`.
-
-    Declare `escapeHatch: { reason: "..." }` on the write or query handler
-    (or on the `r.hook(...)` call, if the switch happens inside a hook), or
-    move the logic into an `r.systemScope()` feature or a job.
-
-identity_switch_denied:
-  endUser: |
-    This action isn't allowed.
-    Please contact an administrator if you believe this is a mistake.
-  developer: |
-    `AccessDeniedError`: a handler or hook called `ctx.queryAs`/`ctx.writeAs`
-    with an identity other than its own caller — a different user id, tenant,
-    claims or origin, or roles the caller does not have — without being an
-    `r.systemScope()` handler, a job, or declaring `escapeHatch: { reason }`.
-    Switching to the caller itself or to a subset of its roles stays free.
-
-    Declare `escapeHatch: { reason: "..." }` on the write or query handler
-    (or on the `r.hook(...)` call, if the switch happens inside a hook), or
-    move the logic into an `r.systemScope()` feature or a job.
-
-unsafe_all_tenants_denied:
-  endUser: |
-    This action isn't allowed.
-    Please contact an administrator if you believe this is a mistake.
-  developer: |
-    `AccessDeniedError`: a handler or hook called
-    `ctx.queryProjection(qualifiedName, { unsafeAllTenants: true })` without
-    being an `r.systemScope()` handler or declaring `escapeHatch: { reason }`.
-
-    Declare `escapeHatch: { reason: "..." }` on the write, query or stream
-    handler (or on the `r.hook(...)` call, if the read happens inside a
-    hook), or move the logic into an `r.systemScope()` feature.
-
-member_resolution_denied:
-  endUser: |
-    This action isn't allowed.
-    Please contact an administrator if you believe this is a mistake.
-  developer: |
-    `AccessDeniedError`: `ctx.queryAsMember(userId, ...)` could not resolve an
-    active membership for `userId` in the caller's tenant (not a member,
-    principal blocked, or the tenant is in teardown). Deliberately generic —
-    `details` never says which check failed.
-
-member_resolution_read_only:
-  endUser: |
-    This action isn't allowed.
-    Please contact an administrator if you believe this is a mistake.
-  developer: |
-    `AccessDeniedError`: a query handler reached via `ctx.queryAsMember` tried
-    to write (`ctx.write`/`writeAs`/`appendEvent`/`jobRunner`/...). Resolved
-    member principals are read-only — there is no `writeAsMember`.
-
-public_intake_required:
-  endUser: |
-    This action isn't allowed.
-    Please contact an administrator if you believe this is a mistake.
-  developer: |
-    `AccessDeniedError`: a write under an anonymous root handler touched a
-    personal-data field (`pii` / `userOwned` / `recordOwned`), directly or via
-    `ctx.write`/`writeAs`/`queryAs` or a hook. `details` name `rootHandler`,
-    `target` and `fields`. Declare
-    `access: { roles: [..., "anonymous"], personalData: "public-intake" }` on
-    the root handler if the anonymous intake is intended.
-
-irreversible_operation_requires_high_risk:
-  endUser: |
-    This action isn't allowed.
-    Please contact an administrator if you believe this is a mistake.
-  developer: |
-    `AccessDeniedError`: the directly-dispatched entry handler performs a hard
-    delete or `forget` (`details.operation`) but its resolved agent risk
-    (`details.resolvedRisk`) is below `"high"`. `details.handler` names the
-    entry handler — delegating the call via `ctx.write`/`writeAs` from a
-    lower-risk handler does not inherit an inner handler's declared risk.
-
-    Declare `agent: { risk: "high" }` on the named handler.
-
-instruction_field_write_requires_high_risk:
-  endUser: |
-    This action isn't allowed.
-    Please contact an administrator if you believe this is a mistake.
-  developer: |
-    `AccessDeniedError`: the directly-dispatched entry handler writes a field
-    flagged `readAsInstruction: true` (`details.fields`) but its resolved
-    agent risk (`details.resolvedRisk`) is below `"high"`. `details.handler`
-    names the entry handler — delegating the call via `ctx.write`/`writeAs`
-    from a lower-risk handler does not inherit an inner handler's declared
-    risk.
-
-    Declare `agent: { risk: "high" }` on the named handler.
-
-agent.tool_not_allowed:
-  endUser: |
-    This tool is not available in the current mode.
-    Switch the assistant to a mode that covers this action, or do it yourself
-    in the app.
-  developer: |
-    `AccessDeniedError` from the agent's tool dispatch: the model asked for a
-    tool name outside the catalog built for this run — a hallucinated name, or
-    a handler the current agent mode doesn't expose.
-
-    The catalog is derived from the mounted registry (`buildToolCatalog`), so a
-    handler without a `description` never becomes a tool at all. Describe the
-    handler, or widen the agent mode, if the call was meant to work.
-
-agent.iteration_limit:
-  endUser: |
-    The assistant reached the maximum number of steps without a clear answer.
-    Please rephrase the request or split it into smaller steps.
-  developer: |
-    `UnprocessableError` from the agent loop: the run hit its maximum round
-    count before the model produced a final answer — usually a tool that keeps
-    returning the same error, or a task that needs more steps than the limit
-    allows.
-
-    Raise the round limit for the run, or narrow the task. The conversation's
-    turn history shows which tool call kept repeating.
-
-agent.permission_denied:
-  endUser: |
-    You don't have permission for this action.
-    The assistant can only do what your own account is allowed to do.
-  developer: |
-    `AccessDeniedError` from the agent's tool dispatch: the tool exists in the
-    catalog, but the caller's roles don't cover the handler behind it. The
-    agent runs strictly with the calling user's permissions — it never
-    escalates.
-
-    Grant the role on the handler, or accept that this tool stays unavailable
-    for that user.
-
-agent.high_risk_no_always:
-  endUser: |
-    High-risk actions can't be set to "always allow".
-    Every run of this action needs your explicit confirmation.
-  developer: |
-    `AccessDeniedError` from the agent's risk gate: a handler declared
-    `agent: { risk: "high" }` was invoked without the explicit per-call
-    confirmation such handlers require, or an "always allow" rule was requested
-    for one.
-
-    Lower the declared risk if the action really is routine; otherwise the
-    confirmation prompt is the intended behaviour.

package/src/errors/index.ts

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

package/src/errors/kumiko-error.ts

@@ -1,67 +0,0 @@
-// 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.
-
-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;
-};
-
-// 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(): string {
-  return process.env["KUMIKO_DOCS_URL"] ?? DEFAULT_DOCS_BASE_URL;
-}
-
-export 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) {
-    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(): string {
-    return `${docsBaseUrl()}/errors/${encodeURIComponent(this.reasonSlug)}`;
-  }
-
-  private get reasonSlug(): string {
-    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 as Record<string, unknown>)["reason"];
-      if (typeof r === "string" && REASON_SLUG_RE.test(r)) return r;
-    }
-    return this.code;
-  }
-}
-
-export function isKumikoError(e: unknown): e is KumikoError {
-  return e instanceof KumikoError;
-}

package/src/errors/member-resolution.ts

@@ -1,12 +0,0 @@
-import { AccessDeniedError } from "./classes";
-import { FrameworkReasons } from "./reasons";
-
-// Lives in errors/ (not pipeline/) so db/tenant-db.ts can throw it without importing pipeline.
-export function memberResolutionReadOnlyDenied(cause?: unknown): AccessDeniedError {
-  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 }),
-  });
-}