@cosmicdrift/kumiko-framework 0.220.1 → 0.222.0

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";
 
@@ -147,6 +146,15 @@ export function applyChanges(sourceFile: SourceFile, changes: readonly PatternCh
  * biome-stable formatting that matches the renderFeatureFile output.
  */
 export function addPattern(sourceFile: SourceFile, pattern: FeaturePattern): void {
+  if (
+    pattern.kind === "ai.generate" ||
+    pattern.kind === "ai.extract" ||
+    pattern.kind === "ai.classify"
+  ) {
+    throw new Error(
+      `addPattern: ${pattern.kind} steps must be inserted into a defineWorkflow steps array, not the setup body`,
+    );
+  }
   const setup = findSetupCallback(sourceFile);
   if (!setup) {
     throw new Error("addPattern: no defineFeature(name, (r) => { ... }) call found");
@@ -195,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.
@@ -357,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;
@@ -391,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/role-assignment.ts

@@ -1,45 +1,63 @@
-const ROLE_RANKS: Readonly<Record<string, number>> = {
-  User: 0,
+// Prototype-free rank table — Object literals leak Object.prototype
+// (`constructor`, `toString`, …) into `ROLE_RANKS[role]` lookups and turn
+// Math.max into NaN, which fails every `rank > actorRank` check open.
+const ROLE_RANKS = new Map<string, number>([
+  ["User", 0],
   // Matches DEFAULT_INVITE_ROLE_OPTIONS — must stay ranked or invite UI fails closed.
-  Editor: 1,
-  Admin: 2,
-  TenantAdmin: 3,
-  SystemAdmin: 4,
-  system: 5,
-};
+  ["Editor", 1],
+  ["Admin", 2],
+  ["TenantAdmin", 3],
+  ["SystemAdmin", 4],
+  ["system", 5],
+]);
+
+// Unknown roles: +∞ on the assigned path (cannot grant what we don't know),
+// -1 on the actor path (cannot elevate via an unrecognized self-role).
+function roleRankOr(role: string, unknownRank: number): number {
+  return ROLE_RANKS.get(role) ?? unknownRank;
+}
 
 function getRoleRank(role: string): number {
-  return ROLE_RANKS[role] ?? Number.POSITIVE_INFINITY;
+  return roleRankOr(role, Number.POSITIVE_INFINITY);
 }
 
 function maxRoleRank(roles: readonly string[]): number {
   if (roles.length === 0) return -1;
-  return Math.max(...roles.map((role) => ROLE_RANKS[role] ?? -1));
+  return Math.max(...roles.map((role) => roleRankOr(role, -1)));
 }
 
 /** Known built-in rank only — unranked app roles (Billing, …) are not privilege tiers. */
 function knownRoleRank(role: string): number | undefined {
-  return ROLE_RANKS[role];
+  return ROLE_RANKS.get(role);
 }
 
 export function findForbiddenRoleAssignment(
   actorRoles: readonly string[],
   assignedRoles: readonly string[],
-  targetCurrentRoles: readonly string[] = [],
+  // Required so callers cannot accidentally disable the downgrade/
+  // takeover guard by omitting the third argument (new users: pass []).
+  targetCurrentRoles: readonly string[],
 ): string | undefined {
   const actorRank = maxRoleRank(actorRoles);
-  // Assign path: fail-closed on unknown / above-actor roles.
-  const forbiddenAssigned = assignedRoles.find((role) => getRoleRank(role) > actorRank);
-  if (forbiddenAssigned) return forbiddenAssigned;
+  // Assign path: fail-closed on unknown / above-actor roles — except unranked
+  // app roles the target already holds (round-trip restore after strip).
+  const forbiddenAssigned = assignedRoles.find((role) => {
+    if (getRoleRank(role) <= actorRank) return false;
+    if (knownRoleRank(role) === undefined && targetCurrentRoles.includes(role)) return false;
+    return true;
+  });
+  // Empty string is unknown (rank +∞) but falsy — must not use truthiness.
+  if (forbiddenAssigned !== undefined) return forbiddenAssigned;
 
   // Target path: only ranked roles above the actor block (can't touch a
-  // SystemAdmin). Unranked app roles must not block demotion/updates — invite
-  // can assign them; treating them as rank ∞ on the target freezes those members.
+  // SystemAdmin). Unranked app roles are ignored here so members with only
+  // those roles don't freeze on demotion/updates — the assign path still
+  // rejects *new* unranked roles fail-closed.
   const forbiddenTarget = targetCurrentRoles.find((role) => {
     const rank = knownRoleRank(role);
     return rank !== undefined && rank > actorRank;
   });
-  if (forbiddenTarget) return forbiddenTarget;
+  if (forbiddenTarget !== undefined) return forbiddenTarget;
 
   return undefined;
 }

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,
@@ -65,6 +66,11 @@ describe("KumikoError: abstract base", () => {
       const body = serializeError(err);
       expect(body.error.docsUrl).toBe("https://docs.kumiko.rocks/errors/stale_state");
     });
+
+    test("falls back to code when reason slug is not URL-safe", () => {
+      const err = new ConflictError({ details: { reason: "stale state/../x" } });
+      expect(err.docsUrl).toBe("https://docs.kumiko.rocks/errors/conflict");
+    });
   });
 });
 
@@ -324,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");
@@ -421,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

@@ -12,20 +12,30 @@ describe("failNotFound", () => {
 });
 
 describe("failUnprocessable", () => {
-  test("baut WriteFailure mit reason + custom-details", () => {
+  test("builds WriteFailure with reason + custom details", () => {
     const f = failUnprocessable("custom_business_rule", { extra: 42 });
     expect(f.error.httpStatus).toBe(422);
     expect(f.error.details).toMatchObject({ reason: "custom_business_rule", extra: 42 });
   });
 
-  test("reason-Argument überlebt ein details.reason aus dem Aufruf", () => {
+  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", () => {
-  test("baut WriteFailure mit reason=invalid_transition + from/to/allowed", () => {
+  test("builds WriteFailure with reason=invalid_transition + from/to/allowed", () => {
     const f = failTransition("draft", "paid", ["sent"]);
     expect(f.isSuccess).toBe(false);
     expect(f.error.code).toBe("unprocessable");

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/kumiko-error.ts

@@ -19,10 +19,10 @@ export type ErrorCtorInput = {
   readonly cause?: Error;
 };
 
-// Default-Doku-URL für Self-Service-Errors. Kann via env-var
-// `KUMIKO_DOCS_URL` überschrieben werden — z.B. für Self-Hosted-Kunden
-// die ihre eigene Doku-Instanz hosten.
+// 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;
@@ -43,20 +43,20 @@ export abstract class KumikoError extends Error {
     this.details = input.details;
   }
 
-  // Doku-URL für Self-Service. Pro-Reason-Slug aus `details.reason` wenn
-  // vorhanden (z.B. ConflictError → "stale_state"), sonst Fallback auf
-  // den Error-Code (z.B. "not_found", "validation_error"). Default-Renderer
-  // im Client zeigt "Mehr erfahren →" Link auf diese URL.
+  // 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/${this.reasonSlug}`;
+    return `${docsBaseUrl()}/errors/${encodeURIComponent(this.reasonSlug)}`;
   }
 
   private get reasonSlug(): string {
     if (this.details && typeof this.details === "object") {
-      // @cast-boundary error-details — KumikoError.details ist per-error
-      // typed, hier reines reflection-shape für reasonSlug-Lookup.
+      // @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") return r;
+      if (typeof r === "string" && REASON_SLUG_RE.test(r)) return r;
     }
     return this.code;
   }

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/event-store/__tests__/backfill-pii.integration.test.ts

@@ -7,6 +7,7 @@
 // blind-index column, so equality lookups keep working.
 
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
 import {
   resetBlindIndexKeyForTests,
   resetPiiSubjectKmsForTests,
@@ -18,6 +19,7 @@ import {
   InMemoryKmsAdapter,
   isPiiCiphertext,
   KeyNotFoundError,
+  PgKmsAdapter,
   PII_ERASED_SENTINEL,
 } from "../../crypto";
 import { applyEntityEvent } from "../../db/apply-entity-event";
@@ -277,6 +279,62 @@ describe("backfillEventPiiEncryption", () => {
     expect(real.erasedUnresolvable).toBe(dry.erasedUnresolvable);
   });
 
+  // The prod bug this regression test guards (fw#2255) only ever manifested
+  // against a real subject-keys store (kumiko_subject_keys 20→22 rows during
+  // a dry run) — the InMemoryKmsAdapter tests above can't see that, since
+  // there is no row store to leak into. Run the same dry-run invariant
+  // against PgKmsAdapter on real Postgres and assert on the table itself.
+  test("dryRun against PgKmsAdapter mints no row in kumiko_subject_keys (fw#2255)", async () => {
+    const c1 = generateId();
+    await appendPlain(c1, "contact", "contact.created", { id: c1, email: "a@x.com" });
+
+    const baseUrl = process.env["TEST_DATABASE_URL"];
+    if (!baseUrl) throw new Error("Missing required env var: TEST_DATABASE_URL");
+    const pgKms = new PgKmsAdapter({
+      databaseUrl: baseUrl.replace(/\/[^/]+$/, `/${testDb.dbName}`),
+      platformKek: randomBytes(32).toString("base64"),
+      maxConnections: 1,
+    });
+    const raw = asRawClient(testDb.db);
+    try {
+      // health() creates kumiko_subject_keys lazily so the counts below see
+      // a real (empty) table instead of failing on "relation does not exist".
+      await pgKms.health();
+      configurePiiSubjectKms(pgKms);
+
+      const before = (await raw.unsafe(
+        `SELECT count(*)::int AS n FROM kumiko_subject_keys`,
+      )) as ReadonlyArray<{ n: number }>;
+
+      const dry = await backfillEventPiiEncryption(testDb.db, registry, { dryRun: true });
+      expect(dry.failures).toEqual([]);
+      expect(dry.encryptedFields).toBe(1);
+
+      const afterDry = (await raw.unsafe(
+        `SELECT count(*)::int AS n FROM kumiko_subject_keys`,
+      )) as ReadonlyArray<{ n: number }>;
+      expect(afterDry[0]?.n).toBe(before[0]?.n);
+      await expect(
+        pgKms.getKey({ kind: "user", userId: c1 }, { requestId: "backfill-pii-test" }),
+      ).rejects.toThrow(KeyNotFoundError);
+
+      // The real run does mint exactly one row through the same Pg path —
+      // proves the invariant above is a genuine "dry run creates nothing",
+      // not an adapter that never creates rows at all.
+      const real = await backfillEventPiiEncryption(testDb.db, registry);
+      expect(real.encryptedFields).toBe(1);
+      const afterReal = (await raw.unsafe(
+        `SELECT count(*)::int AS n FROM kumiko_subject_keys`,
+      )) as ReadonlyArray<{ n: number }>;
+      expect(afterReal[0]?.n).toBe((before[0]?.n ?? 0) + 1);
+      await expect(
+        pgKms.getKey({ kind: "user", userId: c1 }, { requestId: "backfill-pii-test" }),
+      ).resolves.toBeInstanceOf(Buffer);
+    } finally {
+      await pgKms.close();
+    }
+  });
+
   test("dryRun on a KMS-era-erased subject (no *.forgotten event) predicts [[erased]] without touching the key store", async () => {
     const author = generateId();
     const noteId = generateId();

package/src/event-store/__tests__/perf.integration.test.ts

@@ -13,7 +13,7 @@
 // are the ceiling.
 //
 // Runs isolated in the `event-store-perf` CI job (test:integration:perf:eventstore,
-// #1940) — see that job's comment in ci.yml for why the gate is p95 not p99.
+// #1940) — gate on p95 for typical latency; p99 keeps a separate tail budget for checkpoint/fsync spikes.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
@@ -103,6 +103,8 @@ describe("event-store performance — Gate A", () => {
     );
 
     expect(p95).toBeLessThan(30);
+    // Tail budget: cold-checkpoint/fsync spikes after warm-up, not connection warm-up.
+    expect(p99).toBeLessThan(100);
   });
 
   test("read-latency p95 < 25ms for loadAggregate detail reads", async () => {
@@ -143,6 +145,7 @@ describe("event-store performance — Gate A", () => {
     // 25ms budget kept from the original spike doc's 10ms — an
     // order-of-magnitude gate, not an idle-best-case one. Tracking: #325.
     expect(p95).toBeLessThan(25);
+    expect(p99).toBeLessThan(100);
   });
 
   test("update-latency p95 < 30ms — exercises predecessor-check WHERE EXISTS path", async () => {
@@ -202,6 +205,7 @@ describe("event-store performance — Gate A", () => {
     );
 
     expect(p95).toBeLessThan(30);
+    expect(p99).toBeLessThan(100);
   });
 
   test("snapshot-load < 50ms for 1000-event aggregate (Gate A)", async () => {

package/src/event-store/__tests__/unscoped-stream-primitives.guard.test.ts

@@ -51,6 +51,7 @@ describe("unscoped stream primitives — caller allowlist", () => {
     // Positive control — proves the scan actually ran and found the known
     // caller, not just that it (silently) found nothing.
     expect(matches.has("packages/bundled-features/src/tenant/seeding.ts")).toBe(true);
+    expect(matches.has("packages/framework/src/event-store/event-store.ts")).toBe(true);
 
     const offenders = [...matches].filter((relPath) => !ALLOWED_FILES.has(relPath));
     expect(offenders).toEqual([]);

package/src/event-store/event-store.ts

@@ -279,6 +279,13 @@ export async function getUnscopedAggregateStreamMaxVersion(
 // the bigserial PK index — sub-millisecond cost. Returns 0n on an empty log
 // (boot, fresh tenant, post-archive).
 // @wrapper-known semantic-alias
+/** Seed/orphan helper — prefer this over importing the restricted existence-oracle by name. */
+export async function getUnscopedStreamMaxVersionForSeed(
+  ...args: Parameters<typeof getUnscopedAggregateStreamMaxVersion>
+): ReturnType<typeof getUnscopedAggregateStreamMaxVersion> {
+  return getUnscopedAggregateStreamMaxVersion(...args);
+}
+
 export async function getEventsHighWaterMark(db: DbRunner): Promise<bigint> {
   return selectEventsHighWaterMark(db);
 }