@cosmicdrift/kumiko-framework 0.221.0 → 0.222.0

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 }),
+    });
   }
 }
 

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

@@ -35,7 +35,7 @@ export function failNotFound(entity: string, id?: number | string): WriteFailure
 // @wrapper-known error-helper
 export function failUnprocessable(
   reason: string,
-  details?: Readonly<Record<string, unknown>>,
+  details?: Readonly<Record<string, unknown>> & { readonly reason?: never },
 ): WriteFailure {
   return writeFailure(new UnprocessableError(reason, details ? { details } : undefined));
 }

package/src/files/__tests__/local-provider.contract.test.ts

@@ -0,0 +1,14 @@
+import { afterAll } from "bun:test";
+import { rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describeFileProviderContract } from "../../testing/file-provider-contract";
+import { createLocalProvider } from "../local-provider";
+
+const basePath = join(tmpdir(), `kumiko-local-provider-contract-${Date.now()}`);
+
+describeFileProviderContract("LocalFileProvider", () => createLocalProvider(basePath));
+
+afterAll(async () => {
+  await rm(basePath, { recursive: true, force: true });
+});

package/src/files/in-memory-provider.ts

@@ -86,6 +86,10 @@ export function createInMemoryFileProvider(): InMemoryFileProvider {
       return store.has(key);
     },
 
+    async list(prefix) {
+      return Array.from(store.keys()).filter((key) => key.startsWith(prefix));
+    },
+
     // Deterministic fake URL — encodes the key + expiry so tests can assert
     // the route wired through without running a real presigner. Shape
     // (memory://<key>?expires=<seconds>) intentionally differs from any real

package/src/files/local-provider.ts

@@ -1,5 +1,5 @@
 import { createReadStream, createWriteStream } from "node:fs";
-import { mkdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { dirname, join, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { assertSafeStorageKey, type FileStorageProvider } from "./types";
@@ -107,5 +107,26 @@ export function createLocalProvider(basePath: string): FileStorageProvider {
         return false;
       }
     },
+
+    async list(prefix: string): Promise<readonly string[]> {
+      // recursive:true returns POSIX- or OS-sep-joined relative paths for
+      // both files and directories; normalize to "/" (storage keys are
+      // always "/"-joined, matching S3) before the prefix match, then stat
+      // only the (few) matches to drop directory entries.
+      let entries: string[];
+      try {
+        entries = await readdir(resolvedBase, { recursive: true });
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+        throw err;
+      }
+      const results: string[] = [];
+      for (const entry of entries) {
+        const key = entry.split(sep).join("/");
+        if (!key.startsWith(prefix)) continue;
+        if ((await stat(join(resolvedBase, entry))).isFile()) results.push(key);
+      }
+      return results;
+    },
   };
 }