@cosmicdrift/kumiko-framework 0.221.0 → 0.223.0

package/src/engine/extensions/storage-provider.ts

@@ -0,0 +1,28 @@
+// Hook signature types for EXT_STORAGE_PROVIDER (tenant-destroy binary cleanup).
+//
+// Mirror of tenant-data.ts, but the destroyTenant hook takes (tenantId, ctx)
+// rather than just (ctx) — runExtensionDestroyHooks (tenant-lifecycle/stages.ts)
+// passes tenantId as its own positional arg for every EXT_*_RESOURCE-style
+// extension point, not just this one. ctx here only guarantees tenantId plus
+// the optional fileProviderResolver/log; the richer stage-runner ctx
+// (tenant-lifecycle's DestructionStageCtx) is a structural superset, so a hook
+// typed against this minimal ctx is safely assignable wherever that richer ctx
+// is passed.
+
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
+import type { TenantId } from "../types";
+
+export interface StorageProviderHookCtx {
+  readonly tenantId: TenantId;
+  readonly fileProviderResolver?: FileProviderResolver;
+  readonly log?: (message: string) => void;
+}
+
+export type StorageProviderDestroyTenantHook = (
+  tenantId: TenantId,
+  ctx: StorageProviderHookCtx,
+) => Promise<void>;
+
+export interface StorageProviderExtensionHooks {
+  readonly destroyTenant: StorageProviderDestroyTenantHook;
+}

package/src/engine/extensions/user-data.ts

@@ -66,6 +66,10 @@ export type TenantUserModel = "single-user" | "multi-user";
  */
 export interface UserDataStorageProvider {
   delete(storageKey: string): Promise<void>;
+  // Needed so a forget/tenant-destroy hook can find derived/variant keys
+  // (thumbnails, resized variants) that are never tracked anywhere but the
+  // storage layer itself — see fileRefDeleteHook.
+  list(prefix: string): Promise<readonly string[]>;
 }
 
 export interface UserDataHookCtx {

package/src/engine/factories.ts

@@ -162,25 +162,32 @@ export function createSelectField<
 }
 
 /**
- * Multi-Select-Field — N Werte aus einer festen Options-Liste.
+ * Multi-select field — N values from a fixed option list.
  *
- * Storage: jsonb-Array<string>. Jeder Eintrag muss in `options` enthalten
- * sein (Boot-Validator). UI-Renderer rendert das als Checkbox-Group oder
- * Multi-Select-Dropdown.
+ * Storage: jsonb-Array<string>. Every entry must be in `options`
+ * (boot-validator). Renders as a combobox dropdown by default; set
+ * `display: "checkboxes"` to render every option as a visible checkbox with
+ * a select-all toggle instead.
  *
  * ```ts
  * licenceClasses: createMultiSelectField({
  *   options: ["B", "BE", "C", "C1", "CE", "C1E", "D", "D1"] as const,
  *   default: ["B"],
  * }),
+ *
+ * languages: createMultiSelectField({
+ *   options: ["en", "de", "es", "fr", "it"] as const,
+ *   display: "checkboxes",
+ *   columns: 2,
+ * }),
  * ```
  *
  * Caller-API:
  *   Write: `{ licenceClasses: ["B", "BE", "C1"] }`
  *   Read:  `{ licenceClasses: ["B", "BE", "C1"] }`
  *
- * Wann statt `select`: wenn mehrere Werte gleichzeitig erlaubt sind.
- * Wann statt `embedded` mit Booleans: bei mehr als ~5 Optionen.
+ * Use instead of `select` when more than one value can be chosen at once.
+ * Use instead of `embedded` with booleans once there are more than ~5 options.
  */
 export function createMultiSelectField<const TOptions extends readonly string[]>(
   opts: { options: TOptions } & Partial<

package/src/engine/feature-ast/__tests__/parse.test.ts

@@ -2588,7 +2588,7 @@ describe("cross-file registrar-wrapper resolution against a real filesystem Proj
 
   test("resolves the imported wrapper and recognises the nav pattern it registers", () => {
     expect(result.errors).toEqual([]);
-    expect(result.patterns.map((p) => p.kind)).toEqual(["nav", "requires"]);
+    expect(result.patterns.map((p) => p.kind)).toEqual(["requires", "nav"]);
   });
 
   test("the resolved pattern's source points at the imported file, not the entry file", () => {

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -869,9 +869,7 @@ describe("render → parse roundtrip — AI pipeline steps", () => {
 
   test("inline + const-ref ai steps round-trip structurally", () => {
     const aiPatterns = initial.patterns.filter((p) => p.kind.startsWith("ai."));
-    const stepCalls = aiPatterns
-      .map((p) => indent(renderPattern(p), "      ").replace(/;\s*$/, ","))
-      .join("\n");
+    const stepCalls = aiPatterns.map((p) => `${indent(renderPattern(p), "      ")},`).join("\n");
     const wrapped = `
 import { defineFeature, defineWorkflow, stepsPipeline } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";

package/src/engine/feature-ast/extractors/ai-steps.ts

@@ -1,5 +1,4 @@
-import type { CallExpression, Node, ObjectLiteralExpression, SourceFile } from "ts-morph";
-import { SyntaxKind } from "ts-morph";
+import type { CallExpression, ObjectLiteralExpression, SourceFile } from "ts-morph";
 import type {
   AiClassifyPattern,
   AiExtractPattern,
@@ -17,7 +16,10 @@ import {
   isRawRefSentinel,
   ok,
   readDataLiteralNode,
+  readNameLiteral,
+  readObjectPropertyInitializer,
   readStringOrRaw,
+  resolveSameFileObjectLiteral,
 } from "./shared";
 
 type AiStepKind = AiGeneratePattern["kind"] | AiExtractPattern["kind"] | AiClassifyPattern["kind"];
@@ -32,33 +34,11 @@ type AiStepCommonExtracted = {
   readonly paramsSchemaSource?: SourceLocation;
 };
 
-function resolveObjectLiteralArg(node: Node): ObjectLiteralExpression | undefined {
-  const direct = node.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (direct) return direct;
-  const identifier = node.asKind(SyntaxKind.Identifier);
-  if (!identifier) return undefined;
-  const varDecl = node.getSourceFile().getVariableDeclaration(identifier.getText());
-  return varDecl?.getInitializer()?.asKind(SyntaxKind.ObjectLiteralExpression);
-}
-
-function readPropertyInitializer(
-  obj: ObjectLiteralExpression,
-  propertyName: string,
-): import("ts-morph").Expression | undefined {
-  const prop = obj.getProperty(propertyName);
-  if (!prop) return undefined;
-  const assign = prop.asKind(SyntaxKind.PropertyAssignment);
-  if (assign) return assign.getInitializer();
-  const shorthand = prop.asKind(SyntaxKind.ShorthandPropertyAssignment);
-  if (shorthand) return shorthand.getNameNode();
-  return undefined;
-}
-
 function readEditableStringProp(
   obj: ObjectLiteralExpression,
   propertyName: string,
 ): string | AiStepOpaqueArgs | undefined {
-  const init = readPropertyInitializer(obj, propertyName);
+  const init = readObjectPropertyInitializer(obj, propertyName);
   if (!init) return undefined;
   const value = readStringOrRaw(init);
   if (value === undefined) return undefined;
@@ -108,7 +88,7 @@ function extractAiStepCommon(
     return fail(kind, source, "expected one argument object");
   }
 
-  const obj = resolveObjectLiteralArg(arg);
+  const obj = resolveSameFileObjectLiteral(arg);
   if (!obj) {
     if (isRawRefSentinel(readDataLiteralNode(arg))) {
       return ok({
@@ -123,15 +103,21 @@ function extractAiStepCommon(
     );
   }
 
-  const stepKey = readEditableStringProp(obj, "stepKey");
-  if (stepKey === undefined) {
+  const stepKeyInit = readObjectPropertyInitializer(obj, "stepKey");
+  if (!stepKeyInit) {
     return fail(kind, source, "missing `stepKey` property");
   }
+  // PatternId needs a concrete string — resolve identifiers like patch.readAiStepKey.
+  const stepKeyLiteral = readNameLiteral(stepKeyInit);
+  const stepKey = stepKeyLiteral ?? readStringOrRaw(stepKeyInit);
+  if (stepKey === undefined) {
+    return fail(kind, source, "`stepKey` must be a string literal or resolvable identifier");
+  }
   const promptKey = readEditableStringProp(obj, "promptKey");
   if (promptKey === undefined) {
     return fail(kind, source, "missing `promptKey` property");
   }
-  const promptFallbackInit = readPropertyInitializer(obj, "promptFallback");
+  const promptFallbackInit = readObjectPropertyInitializer(obj, "promptFallback");
   if (!promptFallbackInit) {
     return fail(kind, source, "missing `promptFallback` property");
   }
@@ -140,7 +126,7 @@ function extractAiStepCommon(
     return fail(kind, source, "`promptFallback` must be a string literal or identifier reference");
   }
 
-  const defaultsInit = readPropertyInitializer(obj, "defaults");
+  const defaultsInit = readObjectPropertyInitializer(obj, "defaults");
   if (!defaultsInit) {
     return fail(kind, source, "missing `defaults` property");
   }
@@ -149,7 +135,7 @@ function extractAiStepCommon(
     return fail(kind, source, "`defaults` could not be read as a StepPolicy literal");
   }
 
-  const paramsSchemaInit = readPropertyInitializer(obj, "paramsSchema");
+  const paramsSchemaInit = readObjectPropertyInitializer(obj, "paramsSchema");
   if (!paramsSchemaInit) {
     return fail(kind, source, "missing `paramsSchema` property");
   }
@@ -206,11 +192,11 @@ export function extractAiGenerate(
   }
 
   const arg = call.getArguments()[0];
-  const obj = arg ? resolveObjectLiteralArg(arg) : undefined;
+  const obj = arg ? resolveSameFileObjectLiteral(arg) : undefined;
   if (!obj) {
     return fail("ai.generate", common.pattern.source, "expected resolvable argument object");
   }
-  const inputInit = readPropertyInitializer(obj, "input");
+  const inputInit = readObjectPropertyInitializer(obj, "input");
   if (!inputInit) {
     return fail("ai.generate", common.pattern.source, "missing `input` property");
   }
@@ -252,16 +238,16 @@ export function extractAiExtract(
   }
 
   const arg = call.getArguments()[0];
-  const obj = arg ? resolveObjectLiteralArg(arg) : undefined;
+  const obj = arg ? resolveSameFileObjectLiteral(arg) : undefined;
   if (!obj) {
     return fail("ai.extract", common.pattern.source, "expected resolvable argument object");
   }
 
-  const outputSchemaInit = readPropertyInitializer(obj, "outputSchema");
+  const outputSchemaInit = readObjectPropertyInitializer(obj, "outputSchema");
   if (!outputSchemaInit) {
     return fail("ai.extract", common.pattern.source, "missing `outputSchema` property");
   }
-  const instructionsInit = readPropertyInitializer(obj, "instructions");
+  const instructionsInit = readObjectPropertyInitializer(obj, "instructions");
   if (!instructionsInit) {
     return fail("ai.extract", common.pattern.source, "missing `instructions` property");
   }
@@ -274,7 +260,7 @@ export function extractAiExtract(
     );
   }
 
-  const documentInit = readPropertyInitializer(obj, "document");
+  const documentInit = readObjectPropertyInitializer(obj, "document");
   let documentBody: SourceLocation | undefined;
   if (documentInit) {
     const documentFn = findFunctionLiteral(documentInit);
@@ -319,12 +305,12 @@ export function extractAiClassify(
   }
 
   const arg = call.getArguments()[0];
-  const obj = arg ? resolveObjectLiteralArg(arg) : undefined;
+  const obj = arg ? resolveSameFileObjectLiteral(arg) : undefined;
   if (!obj) {
     return fail("ai.classify", common.pattern.source, "expected resolvable argument object");
   }
 
-  const actionsInit = readPropertyInitializer(obj, "actions");
+  const actionsInit = readObjectPropertyInitializer(obj, "actions");
   if (!actionsInit) {
     return fail("ai.classify", common.pattern.source, "missing `actions` property");
   }
@@ -337,7 +323,7 @@ export function extractAiClassify(
     );
   }
 
-  const inputInit = readPropertyInitializer(obj, "input");
+  const inputInit = readObjectPropertyInitializer(obj, "input");
   if (!inputInit) {
     return fail("ai.classify", common.pattern.source, "missing `input` property");
   }

package/src/engine/feature-ast/extractors/index.ts

@@ -80,7 +80,9 @@ export {
   readDataLiteralNode,
   readNameOrRef,
   readNameOrRefOrList,
+  readObjectPropertyInitializer,
   readPropertyKey,
   readStringLiteralArgs,
   readVarargsOrArrayProp,
+  resolveSameFileObjectLiteral,
 } from "./shared";

package/src/engine/feature-ast/extractors/shared.ts

@@ -1,4 +1,4 @@
-import type { CallExpression, Node } from "ts-morph";
+import type { CallExpression, Node, ObjectLiteralExpression } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
 import { isPlainObject } from "../../../utils/is-plain-object";
 import type { ParseError } from "../parse";
@@ -264,6 +264,31 @@ export function readNameOrRef(node: Node): string | undefined {
   return undefined;
 }
 
+/** Resolve an inline object literal or a same-file `const` that initializes to one. */
+export function resolveSameFileObjectLiteral(node: Node): ObjectLiteralExpression | undefined {
+  const direct = node.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (direct) return direct;
+  const identifier = node.asKind(SyntaxKind.Identifier);
+  if (!identifier) return undefined;
+  const valueDecl = identifier.getSymbol()?.getValueDeclaration();
+  const fromSymbol = valueDecl?.asKind(SyntaxKind.VariableDeclaration);
+  const varDecl = fromSymbol ?? node.getSourceFile().getVariableDeclaration(identifier.getText());
+  return varDecl?.getInitializer()?.asKind(SyntaxKind.ObjectLiteralExpression);
+}
+
+export function readObjectPropertyInitializer(
+  obj: ObjectLiteralExpression,
+  propertyName: string,
+): import("ts-morph").Expression | undefined {
+  const prop = obj.getProperty(propertyName);
+  if (!prop) return undefined;
+  const assign = prop.asKind(SyntaxKind.PropertyAssignment);
+  if (assign) return assign.getInitializer();
+  const shorthand = prop.asKind(SyntaxKind.ShorthandPropertyAssignment);
+  if (shorthand) return shorthand.getNameNode();
+  return undefined;
+}
+
 export function findFunctionLiteral(node: Node): Node | undefined {
   if (node.getKind() === SyntaxKind.ArrowFunction) return node;
   if (node.getKind() === SyntaxKind.FunctionExpression) return node;

package/src/engine/feature-ast/parse.ts

@@ -26,7 +26,6 @@ import type {
   CallExpression,
   Expression,
   Node,
-  ObjectLiteralExpression,
   ParameterDeclaration,
   SourceFile,
 } from "ts-morph";
@@ -74,6 +73,8 @@ import {
   extractWorkspace,
   extractWriteHandler,
   findFunctionLiteral,
+  readObjectPropertyInitializer,
+  resolveSameFileObjectLiteral,
 } from "./extractors";
 import type { FeaturePattern, UnknownPattern } from "./patterns";
 import { type SourceLocation, sourceLocationFromNode } from "./source-location";
@@ -158,7 +159,13 @@ export function parseSourceFile(sourceFile: SourceFile): ParseResult {
 
   walkSetupCallback(setupCallback.getBody(), registrarParamName, sourceFile, patterns, errors);
   walkAiStepCalls(setupCallback.getBody(), registrarParamName, sourceFile, patterns, errors);
-  patterns.sort((a, b) => a.source.start.line - b.source.start.line);
+  // Tie-break on filePath so cross-file registrar wrappers don't interleave by
+  // foreign line numbers alone.
+  patterns.sort((a, b) => {
+    const fileCmp = a.source.file.localeCompare(b.source.file);
+    if (fileCmp !== 0) return fileCmp;
+    return a.source.start.line - b.source.start.line;
+  });
 
   return { featureName, patterns, errors };
 }
@@ -387,28 +394,6 @@ function extractRegistrarMethodName(
   return propAccess.getName();
 }
 
-function readObjectPropertyInitializer(
-  obj: ObjectLiteralExpression,
-  propertyName: string,
-): Expression | undefined {
-  const prop = obj.getProperty(propertyName);
-  if (!prop) return undefined;
-  const assign = prop.asKind(SyntaxKind.PropertyAssignment);
-  if (assign) return assign.getInitializer();
-  const shorthand = prop.asKind(SyntaxKind.ShorthandPropertyAssignment);
-  if (shorthand) return shorthand.getNameNode();
-  return undefined;
-}
-
-function resolveSameFileObjectLiteralArg(node: Node): ObjectLiteralExpression | undefined {
-  const direct = node.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (direct) return direct;
-  const identifier = node.asKind(SyntaxKind.Identifier);
-  if (!identifier) return undefined;
-  const varDecl = node.getSourceFile().getVariableDeclaration(identifier.getText());
-  return varDecl?.getInitializer()?.asKind(SyntaxKind.ObjectLiteralExpression);
-}
-
 function resolveStepsArrayRoot(stepsInit: Expression): Node | undefined {
   const directArray = stepsInit.asKind(SyntaxKind.ArrayLiteralExpression);
   if (directArray) return directArray;
@@ -444,7 +429,7 @@ function collectWorkflowStepArrayRoots(body: Node): Node[] {
   const roots: Node[] = [];
   for (const call of body.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     if (call.getExpression().getText() !== "defineWorkflow") continue;
-    const obj = resolveSameFileObjectLiteralArg(call.getArguments()[0] ?? call);
+    const obj = resolveSameFileObjectLiteral(call.getArguments()[0] ?? call);
     if (!obj) continue;
     const stepsInit = readObjectPropertyInitializer(obj, "steps");
     if (!stepsInit) continue;

package/src/engine/feature-ast/patch.ts

@@ -30,9 +30,8 @@
 // roadmap C-Notes for the canonical-comment-attach Pattern that would
 // preserve prefixed `// kumiko-comment:` markers across roundtrips.
 
-import type { ObjectLiteralExpression } from "ts-morph";
 import { type CallExpression, type Node, type SourceFile, SyntaxKind } from "ts-morph";
-import { readNameLiteral, readNameOrRef } from "./extractors/shared";
+import { readNameLiteral, readNameOrRef, resolveSameFileObjectLiteral } from "./extractors/shared";
 import type { FeaturePattern, FeaturePatternKind } from "./patterns";
 import { indent, PATTERN_INDENT, renderPattern } from "./render";
 
@@ -204,7 +203,9 @@ export function replacePattern(
   const startNode = isAiStepId(id) ? call : (enclosingStatement ?? call);
 
   const startPos = startNode.getStart();
-  const endPos = isAiStepId(id) ? aiStepPatchSpan(sourceFile, call).end : startNode.getEnd();
+  // AI steps live in array literals — replace only the CallExpression so the
+  // surrounding comma stays (comma-eating belongs to removePattern alone).
+  const endPos = isAiStepId(id) ? call.getEnd() : startNode.getEnd();
 
   // Detect column of the original call's first non-whitespace character;
   // the rendered pattern starts at column 0 and gets indented to match.
@@ -366,17 +367,6 @@ const AI_STEP_FACTORY: Readonly<Record<"ai.generate" | "ai.extract" | "ai.classi
   "ai.classify": "aiClassifyStep",
 };
 
-function resolveSameFileObjectLiteral(
-  node: import("ts-morph").Node,
-): ObjectLiteralExpression | undefined {
-  const direct = node.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (direct) return direct;
-  const identifier = node.asKind(SyntaxKind.Identifier);
-  if (!identifier) return undefined;
-  const varDecl = node.getSourceFile().getVariableDeclaration(identifier.getText());
-  return varDecl?.getInitializer()?.asKind(SyntaxKind.ObjectLiteralExpression);
-}
-
 function readAiStepKey(call: CallExpression): string | undefined {
   const arg = call.getArguments()[0];
   if (!arg) return undefined;
@@ -400,11 +390,19 @@ function findAiStepCall(sourceFile: SourceFile, id: PatternId): CallExpression |
     return undefined;
   }
   const factory = AI_STEP_FACTORY[id.kind];
+  const matches: CallExpression[] = [];
   for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     if (call.getExpression().getText() !== factory) continue;
-    if (callMatchesId(call, id)) return call;
+    if (callMatchesId(call, id)) matches.push(call);
   }
-  return undefined;
+  if (matches.length > 1) {
+    throw new Error(
+      `findAiStepCall: ambiguous ${id.kind} stepKey=${JSON.stringify(
+        "stepKey" in id ? id.stepKey : undefined,
+      )} — ${matches.length} matches; disambiguate or include workflowName in PatternId`,
+    );
+  }
+  return matches[0];
 }
 
 function callMatchesId(call: CallExpression, id: PatternId): boolean {

package/src/engine/feature-ast/render.ts

@@ -481,7 +481,7 @@ function renderAiGenerate(p: AiGeneratePattern): string {
   const lines: string[] = ["aiGenerateStep({"];
   renderAiStepCommonFields(lines, p);
   if (p.inputBody !== undefined) lines.push(`  input: ${p.inputBody.raw},`);
-  lines.push("});");
+  lines.push("})");
   return lines.join("\n");
 }
 
@@ -496,7 +496,7 @@ function renderAiExtract(p: AiExtractPattern): string {
     lines.push(`  instructions: ${p.instructionsBody.raw},`);
   }
   if (p.documentBody !== undefined) lines.push(`  document: ${p.documentBody.raw},`);
-  lines.push("});");
+  lines.push("})");
   return lines.join("\n");
 }
 
@@ -506,7 +506,7 @@ function renderAiClassify(p: AiClassifyPattern): string {
   renderAiStepCommonFields(lines, p);
   if (p.actions !== undefined) lines.push(`  actions: ${renderValue(p.actions)},`);
   if (p.inputBody !== undefined) lines.push(`  input: ${p.inputBody.raw},`);
-  lines.push("});");
+  lines.push("})");
   return lines.join("\n");
 }
 

package/src/engine/field-helpers.ts

@@ -22,7 +22,7 @@ export const DEFAULT_CURRENCIES = [
 
 // --- Locale ---
 
-export const DEFAULT_LOCALES = ["de", "en"] as const;
+export const DEFAULT_LOCALES = ["de", "en", "es"] as const;
 
 export function isFileField(field: FieldDefinition | undefined): field is AnyFileFieldDef {
   if (!field) return false;

package/src/engine/index.ts

@@ -96,6 +96,11 @@ export {
   EXT_USER_DATA_ORDER,
   FILE_PROVIDER_CONFIG_KEY,
 } from "./extension-names";
+export type {
+  StorageProviderDestroyTenantHook,
+  StorageProviderExtensionHooks,
+  StorageProviderHookCtx,
+} from "./extensions/storage-provider";
 export type {
   TenantDataDestroyHook,
   TenantDataExtensionHooks,

package/src/engine/pattern-library/mixed-schemas.ts

@@ -243,6 +243,12 @@ const aiStepCommonFields = [
     input: "text",
     required: true,
   },
+  {
+    path: "promptFallback",
+    label: { en: "Prompt fallback", de: "Prompt-Fallback" },
+    input: "text",
+    required: true,
+  },
   {
     path: "defaults",
     label: { en: "Defaults", de: "Defaults" },

package/src/engine/schema-builder.ts

@@ -86,6 +86,7 @@ function embeddedSubFieldToZod(subField: EmbeddedSubFieldDef): z.ZodTypeAny {
   }
 }
 
+// kumiko-lint-ignore complexity-budget field→zod switch is the single schema source of truth
 export function fieldToZod(
   field: FieldDefinition,
   currencies: readonly string[],
@@ -315,8 +316,19 @@ function applyTotalsMatchRefinements(
       for (const [subFieldName, siblingFieldName] of Object.entries(totalsMatch)) {
         const rawRows = values[fieldName];
         const siblingRaw = values[siblingFieldName];
-        // Not sent -> not checkable, not an error (partial update payloads).
-        if (rawRows === undefined || siblingRaw === undefined) continue;
+        // Neither side sent → nothing to check (unrelated partial update).
+        if (rawRows === undefined && siblingRaw === undefined) continue;
+        // One side of a totalsMatch pair without the other → reject. Update
+        // payloads only carry `changes`, so omitting the sibling would otherwise
+        // silently leave sum ≠ total (fw#1841).
+        if (rawRows === undefined || siblingRaw === undefined) {
+          ctx.addIssue({
+            code: "custom",
+            path: [rawRows === undefined ? fieldName : siblingFieldName],
+            message: `totalsMatch requires both "${fieldName}" and "${siblingFieldName}" in the same payload`,
+          });
+          continue;
+        }
         // Not an array -> a different refinement already rejects the shape;
         // this check isn't the right place to report it.
         if (!Array.isArray(rawRows)) continue;

package/src/errors/__tests__/classes.test.ts

@@ -9,6 +9,7 @@ import {
   KumikoError,
   NotFoundError,
   serializeError,
+  UnconfiguredError,
   UnprocessableError,
   ValidationError,
   VersionConflictError,
@@ -329,9 +330,9 @@ describe("UnprocessableError", () => {
     expect(err.i18nKey).toBe("orders.errors.alreadyCancelled");
   });
 
-  test("positional reason survives a conflicting details.reason from the caller", () => {
+  test("positional reason is the sole details.reason (extras allowed)", () => {
     const err = new UnprocessableError("order.already_cancelled", {
-      details: { reason: "some unrelated cause text", orderId: 7 },
+      details: { orderId: 7 },
     });
     expect(err.details).toEqual({ reason: "order.already_cancelled", orderId: 7 });
     expect(err.docsUrl).toBe("https://docs.kumiko.rocks/errors/order.already_cancelled");
@@ -426,3 +427,16 @@ class KumikoErrorStub extends KumikoError {
     super({ message: "stub", i18nKey: "stub", cause: opts.cause });
   }
 }
+
+describe("UnconfiguredError", () => {
+  test("docsUrl uses stable unconfigured slug, not the freestext message", () => {
+    const err = new UnconfiguredError({ feature: "billing", key: "apiKey" });
+    expect(err.docsUrl).toBe("https://docs.kumiko.rocks/errors/unconfigured");
+    expect(err.details).toMatchObject({
+      reason: "unconfigured",
+      feature: "billing",
+      key: "apiKey",
+    });
+    expect(String((err.details as { message?: string }).message)).toContain("apiKey");
+  });
+});

package/src/errors/__tests__/write-failures.test.ts

@@ -19,9 +19,19 @@ describe("failUnprocessable", () => {
   });
 
   test("positional reason survives a conflicting details.reason from the caller", () => {
+    // @ts-expect-error callers must not pass details.reason; positional arg wins at runtime
     const f = failUnprocessable("custom_business_rule", { reason: "raw cause text", extra: 42 });
     expect(f.error.details).toEqual({ reason: "custom_business_rule", extra: 42 });
   });
+
+  test("details may carry extras but reason comes only from the positional arg", () => {
+    const f = failUnprocessable("custom_business_rule", { extra: 42, causeNote: "use opts.cause" });
+    expect(f.error.details).toEqual({
+      reason: "custom_business_rule",
+      extra: 42,
+      causeNote: "use opts.cause",
+    });
+  });
 });
 
 describe("failTransition", () => {

package/src/errors/classes.ts

@@ -192,8 +192,9 @@ export class UniqueViolationError extends ConflictError {
 
 // Business-rule violation. The human-readable reason lives in details.reason
 // so the client can key off it without overloading the top-level code.
-export type UnprocessableOpts = Pick<ErrorOpts, "i18nKey" | "i18nParams" | "cause"> & {
-  readonly details?: Readonly<Record<string, unknown>>;
+export type UnprocessableOpts = Pick<ErrorOpts, "i18nKey" | "i18nParams" | "cause" | "message"> & {
+  // `reason` is owned by the positional ctor arg — callers put cause text in `opts.cause`.
+  readonly details?: Readonly<Record<string, unknown>> & { readonly reason?: never };
 };
 
 export class UnprocessableError extends KumikoError {
@@ -204,7 +205,7 @@ export class UnprocessableError extends KumikoError {
 
   constructor(reason: string, opts?: UnprocessableOpts) {
     super({
-      message: `unprocessable: ${reason}`,
+      message: opts?.message ?? `unprocessable: ${reason}`,
       i18nKey: opts?.i18nKey ?? "errors.unprocessable",
       ...(opts?.i18nParams && { i18nParams: opts.i18nParams }),
       details: { ...opts?.details, reason },
@@ -226,16 +227,16 @@ export class UnconfiguredError extends UnprocessableError {
   override readonly code: string = "unconfigured";
 
   constructor(details: UnconfiguredDetails, opts?: Pick<ErrorOpts, "i18nKey" | "cause">) {
-    super(
-      `${details.feature}: '${details.key}' is empty — tenant must configure it before use.${
-        details.hint ? ` ${details.hint}` : ""
-      }`,
-      {
-        i18nKey: opts?.i18nKey ?? "errors.unconfigured",
-        details,
-        ...(opts?.cause && { cause: opts.cause }),
-      },
-    );
+    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 }),
+    });
   }
 }