@cosmicdrift/kumiko-framework 0.165.0 → 0.165.2

package/src/engine/boot-validator/nav.ts

@@ -115,6 +115,11 @@ export function collectKnownRoles(features: readonly FeatureDefinition[]): Set<s
         for (const r of def.access.roles) roles.add(r);
       }
     }
+    for (const def of Object.values(f.streamHandlers)) {
+      if (def.access && "roles" in def.access) {
+        for (const r of def.access.roles) roles.add(r);
+      }
+    }
   }
   return roles;
 }

package/src/engine/constants.ts

@@ -1,3 +1,6 @@
+import type { ConcurrencyMode } from "@cosmicdrift/kumiko-types/concurrency-mode";
+import type { ConfigScope } from "@cosmicdrift/kumiko-types/config-scope";
+import type { OnDeleteStrategy as OnDeleteStrategyType } from "@cosmicdrift/kumiko-types/relations";
 import type { TenantId } from "./types/identifiers";
 
 // All framework constants as `as const` objects with inferred union types.
@@ -47,14 +50,23 @@ export const LifecycleHookTypes = {
 export type LifecycleHookType = (typeof LifecycleHookTypes)[keyof typeof LifecycleHookTypes];
 
 // --- Config Scopes ---
+// Value object satisfies the canonical ConfigScope union from kumiko-types —
+// a scope added here without a matching kumiko-types member is now a
+// compile error instead of silent drift (#1423/#1439).
 
 export const ConfigScopes = {
   system: "system",
   tenant: "tenant",
   user: "user",
-} as const;
+} as const satisfies Record<string, ConfigScope>;
+
+export type { ConfigScope };
 
-export type ConfigScope = (typeof ConfigScopes)[keyof typeof ConfigScopes];
+// Reverse direction: a member added only to kumiko-types' ConfigScope
+// (not to ConfigScopes above) would otherwise pass the `satisfies` check
+// above unnoticed — this line forces exhaustiveness the other way too.
+const _configScopeExhaustive: Record<ConfigScope, unknown> = ConfigScopes;
+void _configScopeExhaustive;
 
 // --- On Delete Strategies ---
 
@@ -63,11 +75,13 @@ export const OnDeleteStrategies = {
   restrict: "restrict",
   setNull: "setNull",
   nothing: "nothing",
-} as const;
+} as const satisfies Record<OnDeleteStrategyType, OnDeleteStrategyType>;
 
-export type OnDeleteStrategy = (typeof OnDeleteStrategies)[keyof typeof OnDeleteStrategies];
+export type OnDeleteStrategy = OnDeleteStrategyType;
 
 // --- Concurrency Modes ---
+// Value object satisfies the canonical ConcurrencyMode union from
+// kumiko-types — same drift-guard as ConfigScopes above.
 
 export const ConcurrencyModes = {
   parallel: "parallel",
@@ -75,12 +89,20 @@ export const ConcurrencyModes = {
   replace: "replace",
   sequential: "sequential",
   debounce: "debounce",
-} as const;
+} as const satisfies Record<string, ConcurrencyMode>;
 
-export type ConcurrencyMode = (typeof ConcurrencyModes)[keyof typeof ConcurrencyModes];
+export type { ConcurrencyMode };
+
+// Reverse-direction exhaustiveness guard — see the ConfigScope one above.
+const _concurrencyModeExhaustive: Record<ConcurrencyMode, unknown> = ConcurrencyModes;
+void _concurrencyModeExhaustive;
 
 // --- SSE Channels ---
 
 export function tenantChannel(tenantId: TenantId): string {
   return `tenant:${tenantId}`;
 }
+
+export function userAccessChannel(userId: string): string {
+  return `user:${userId}:access`;
+}

package/src/engine/create-app.ts

@@ -53,6 +53,17 @@ export function createApp(config: AppConfig): App {
         }
       }
     }
+    for (const handler of Object.values(feature.streamHandlers)) {
+      if (handler.access && "roles" in handler.access) {
+        for (const role of handler.access.roles) {
+          if (!validRoles.has(role)) {
+            throw new Error(
+              `Unknown role "${role}" in stream handler "${handler.name}" of feature "${feature.name}". Valid roles: ${config.roles.join(", ")}`,
+            );
+          }
+        }
+      }
+    }
     for (const [key, keyDef] of Object.entries(feature.configKeys)) {
       for (const role of [...keyDef.access.read, ...keyDef.access.write]) {
         if (!systemRoles.has(role) && !validRoles.has(role)) {

package/src/engine/effective-features.ts

@@ -1,4 +1,4 @@
-import type { Registry } from "./types";
+import type { FeatureDefinition, Registry } from "./types";
 
 // Callback that returns the current global-toggle override for a feature.
 // `true`  = explicit global row says enabled.
@@ -11,6 +11,16 @@ import type { Registry } from "./types";
 // a Map lookup to keep compute() allocation-light.
 export type ToggleReader = (featureName: string) => boolean | undefined;
 
+// A feature is toggleable iff it declared r.toggleable() at define-time
+// (toggleableDefault set). Non-toggleable features are always-on and ignore
+// overrides entirely — used here, by compose-tier-resolver, and by
+// tier-engine's always-on set to agree on the same rule.
+export function isToggleableFeature(
+  feature: FeatureDefinition,
+): feature is FeatureDefinition & { toggleableDefault: boolean } {
+  return feature.toggleableDefault !== undefined;
+}
+
 // Compute the set of effectively-enabled features for the current call.
 //
 // Rules (AND-combined, any false wins):
@@ -35,7 +45,7 @@ export function computeEffectiveFeatures(
   // Raw enablement, before cascade.
   const raw = new Map<string, boolean>();
   for (const feature of registry.features.values()) {
-    if (feature.toggleableDefault === undefined) {
+    if (!isToggleableFeature(feature)) {
       raw.set(feature.name, true);
       continue;
     }

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

@@ -150,14 +150,22 @@ export type UserDataExportHook = (ctx: UserDataHookCtx) => Promise<UserDataExpor
  * `{status:"incomplete", reason}` to signal a partial success to the
  * cleanup runner (e.g. an external provider call failed) without
  * throwing/rolling back the sub-transaction. Existing `void` returners
- * stay valid unchanged.
+ * stay valid unchanged — including ones explicitly typed
+ * `Promise<void>` (an explicitly-annotated hook, unlike a contextually-
+ * typed arrow literal, needs `void` in the union itself: `void` is not
+ * assignable to `undefined`).
  */
+// Intentional: void (not undefined) is required here so an explicitly-typed
+// `Promise<void>` hook stays assignable (see UserDataDeleteHook's doc
+// comment above).
+export type UserDataDeleteHookResult =
+  // biome-ignore lint/suspicious/noConfusingVoidType: see comment above
+  void | { readonly status: "ok" } | { readonly status: "incomplete"; readonly reason: string };
+
 export type UserDataDeleteHook = (
   ctx: UserDataHookCtx,
   strategy: UserDataDeleteStrategy,
-) => Promise<
-  undefined | { readonly status: "ok" } | { readonly status: "incomplete"; readonly reason: string }
->;
+) => Promise<UserDataDeleteHookResult>;
 
 /**
  * Komplette Hook-Tafel für EXT_USER_DATA. Sprint 2 user-data-rights

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

@@ -100,7 +100,7 @@ export function extractStoreTable(
   sourceFile: SourceFile,
 ): ExtractOutput<never> {
   // The meta argument is always a factory call (defineUnmanagedTable /
-  // buildEntityTableMeta) or a captured identifier — never an inline literal,
+  // deriveEntityTableMeta) or a captured identifier — never an inline literal,
   // so there is nothing to extract statically. A clean ParseError (not
   // UnknownPattern) marks it design-time-unreadable, like entity-by-identifier.
   return fail(

package/src/engine/feature-ui-extensions.ts

@@ -426,14 +426,14 @@ export function buildUiExtensionsMethods<TName extends string>(
         // EntityTableMeta uses snake_case for tableName (matches Postgres
         // convention); we just guard against truly broken input.
         throw new Error(
-          `[Feature ${name}] Raw-table name "${tableName}" must be a ` +
+          `[Feature ${name}] Store-table name "${tableName}" must be a ` +
             `valid identifier (lowercase letters, digits, underscores; start with a letter).`,
         );
       }
       if (state.storeTables[tableName]) {
         throw new Error(
           `[Feature ${name}] r.storeTable("${tableName}") already registered. ` +
-            `Raw-table names must be unique per feature.`,
+            `Store-table names must be unique per feature.`,
         );
       }
       // `read_` is reserved for r.entity()/r.projection() (managed,
@@ -454,7 +454,7 @@ export function buildUiExtensionsMethods<TName extends string>(
         throw new Error(
           `[Feature ${name}] r.storeTable("${tableName}") was given an EntityTableMeta with ` +
             `source: "${meta.source}". r.storeTable() requires source: "unmanaged" (via ` +
-            `defineUnmanagedTable(), or buildEntityTableMeta(..., { source: "unmanaged" })) — ` +
+            `defineUnmanagedTable(), or deriveEntityTableMeta(..., { source: "unmanaged" })) — ` +
             `otherwise the migration generator will treat schema drift on this table as safe ` +
             `to DROP+rebuild, wiping any direct-write data.`,
         );

package/src/engine/hook-helpers.ts

@@ -8,7 +8,9 @@
 //   are logged but don't affect the write. Use for: external systems
 //   (SSE broadcast, search index, email, webhooks).
 
+import type { HookPhase } from "@cosmicdrift/kumiko-types/hook-phase";
+
 export const HookPhases = {
   inTransaction: "inTransaction",
   afterCommit: "afterCommit",
-} as const;
+} as const satisfies Record<HookPhase, HookPhase>;

package/src/engine/index.ts

@@ -52,7 +52,7 @@ export { defineStep, getStep, listStepKinds } from "./define-step";
 export type { WorkflowDefinition, WorkflowInput, WorkflowTrigger } from "./define-workflow";
 export { computeDefinitionFingerprint, defineWorkflow } from "./define-workflow";
 export type { ToggleReader } from "./effective-features";
-export { computeEffectiveFeatures } from "./effective-features";
+export { computeEffectiveFeatures, isToggleableFeature } from "./effective-features";
 export {
   createEntityExecutor,
   defineEntityCreateHandler,

package/src/engine/ownership.ts

@@ -17,6 +17,10 @@
 // Construction: use the `from(ref, column?)` helper. It returns a FromRule
 // ready to drop into an access map.
 
+import {
+  KUMIKO_COLUMNS_SYMBOL,
+  KUMIKO_NAME_SYMBOL,
+} from "@cosmicdrift/kumiko-types/schema-table-types";
 import { toSnakeCase } from "../db/table-builder";
 import type { SessionUser } from "./types";
 
@@ -221,9 +225,6 @@ export function userCanCreateFieldRow(
 const PASS_CLAUSE: OwnershipClause = { kind: "pass" };
 const EMPTY_CLAUSE: OwnershipClause = { kind: "empty" };
 
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
-
 function tableNameOf(table: unknown): string {
   if (table !== null && typeof table === "object") {
     const sym = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];

package/src/engine/registry-ingest.ts

@@ -20,7 +20,7 @@ export function populateFeatureCore(state: RegistryState, feature: FeatureDefini
     state.entityMap.set(name, entity);
     const physical = resolveTableName(name, entity, feature.name);
     const clash = state.physicalTableOwners.get(physical);
-    if (clash?.kind === "raw") {
+    if (clash?.kind === "store") {
       throw new Error(
         `Entity "${name}" (feature "${feature.name}") has physical table "${physical}" which ` +
           `collides with r.storeTable("${physical}") (feature "${clash.featureName}"). ` +
@@ -317,37 +317,37 @@ export function populateProjectionsAndTables(
   // statements that target the same physical table name. Two features
   // registering the same physical tableName would also race two CREATE
   // TABLE statements via migrate-runner.
-  for (const [rawName, rawDef] of Object.entries(feature.storeTables ?? {})) {
-    const existing = state.storeTableMap.get(rawName);
+  for (const [storeName, storeDef] of Object.entries(feature.storeTables ?? {})) {
+    const existing = state.storeTableMap.get(storeName);
     if (existing) {
       throw new Error(
-        `Raw-table "${rawName}" registered by both feature "${existing.featureName}" and ` +
+        `Store-table "${storeName}" registered by both feature "${existing.featureName}" and ` +
           `"${feature.name}". Pick a feature-prefixed name to disambiguate.`,
       );
     }
-    const physicalClash = state.physicalTableOwners.get(rawName);
+    const physicalClash = state.physicalTableOwners.get(storeName);
     if (physicalClash?.kind === "entity") {
       throw new Error(
-        `Raw-table "${rawName}" (feature "${feature.name}") collides with the physical ` +
+        `Store-table "${storeName}" (feature "${feature.name}") collides with the physical ` +
           `table of entity "${physicalClash.owner}" (feature "${physicalClash.featureName}"). ` +
-          `Pick a different tableName — both would emit CREATE TABLE "${rawName}".`,
+          `Pick a different tableName — both would emit CREATE TABLE "${storeName}".`,
       );
     }
-    const piiFields = rawDef.meta.piiSubjectFields ?? [];
-    if (piiFields.length > 0 && !rawDef.piiEncryptedOnWrite) {
+    const piiFields = storeDef.meta.piiSubjectFields ?? [];
+    if (piiFields.length > 0 && !storeDef.piiEncryptedOnWrite) {
       throw new Error(
-        `Raw-table "${rawName}" (feature "${feature.name}") has PII-annotated fields ` +
+        `Store-table "${storeName}" (feature "${feature.name}") has PII-annotated fields ` +
           `(${piiFields.join(", ")}) but direct writes bypass the executor's PII encryption. ` +
           `Encrypt those fields before every insert/update (encryptPiiFieldValues) and declare ` +
           `{ piiEncryptedOnWrite: true }, or drop the subject annotations.`,
       );
     }
-    state.physicalTableOwners.set(rawName, {
-      kind: "raw",
-      owner: rawName,
+    state.physicalTableOwners.set(storeName, {
+      kind: "store",
+      owner: storeName,
       featureName: feature.name,
     });
-    state.storeTableMap.set(rawName, { ...rawDef, featureName: feature.name });
+    state.storeTableMap.set(storeName, { ...storeDef, featureName: feature.name });
   }
 }
 

package/src/engine/registry-state.ts

@@ -1,5 +1,5 @@
 import { applyEntityEvent } from "../db/apply-entity-event";
-import { assertBackingTableSuperset, buildEntityTableMeta } from "../db/entity-table-meta";
+import { assertBackingTableSuperset, deriveEntityTableMeta } from "../db/entity-table-meta";
 import { asEntityTableMeta } from "../db/query";
 import { buildEntityTable } from "../db/table-builder";
 import { type QnType, qualifyEntityName } from "./qualified-name";
@@ -143,7 +143,7 @@ function resolveBackingTable(
         "EntityTableMeta — build it via table() / buildEntityTable.",
     );
   }
-  assertBackingTableSuperset(entityName, buildEntityTableMeta(entityName, entity), tableMeta);
+  assertBackingTableSuperset(entityName, deriveEntityTableMeta(entityName, entity), tableMeta);
   return backingTable as ProjectionDefinition["table"];
 }
 
@@ -202,7 +202,10 @@ export type RegistryState = {
   multiStreamProjectionMap: Map<string, MultiStreamProjectionDefinition>;
   multiStreamProjectionFeatureMap: Map<string, string>;
   storeTableMap: Map<string, StoreTableDef>;
-  physicalTableOwners: Map<string, { kind: "entity" | "raw"; owner: string; featureName: string }>;
+  physicalTableOwners: Map<
+    string,
+    { kind: "entity" | "store"; owner: string; featureName: string }
+  >;
   authClaimsHooks: AuthClaimsHookDef[];
   claimKeyMap: Map<string, ClaimKeyDefinition>;
   screenMap: Map<string, ScreenDefinition>;

package/src/engine/schema-builder.ts

@@ -97,6 +97,7 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
       let schema = z.number();
       if (field.integer) schema = schema.int();
       if (field.min !== undefined) schema = schema.min(field.min);
+      if (field.max !== undefined) schema = schema.max(field.max);
       return field.default !== undefined ? schema.default(field.default) : schema;
     }
     case "decimal": {

package/src/engine/steps/__tests__/duration-utils.test.ts

@@ -0,0 +1,20 @@
+// kumiko-framework#1525: addDuration must not rely on globalThis.Temporal —
+// it's a pure free function called from step handlers before boot may have
+// run ensureTemporalPolyfill() on every code path.
+
+import { describe, expect, test } from "bun:test";
+import { addDuration } from "../_duration-utils";
+
+describe("addDuration — kumiko-framework#1525: no ambient Temporal global", () => {
+  test("adds a duration without relying on globalThis.Temporal", () => {
+    const savedGlobal = (globalThis as { Temporal?: unknown }).Temporal;
+    delete (globalThis as { Temporal?: unknown }).Temporal;
+    try {
+      const result = addDuration("2026-01-01T00:00:00Z", "P1DT1H");
+      expect(result).toBe("2026-01-02T01:00:00Z");
+    } finally {
+      if (savedGlobal === undefined) delete (globalThis as { Temporal?: unknown }).Temporal;
+      else (globalThis as { Temporal?: unknown }).Temporal = savedGlobal;
+    }
+  });
+});

package/src/engine/steps/_duration-utils.ts

@@ -2,6 +2,8 @@
 // Accepts "P1D", "PT1H", "P1Y2M3DT4H5M6S" etc.
 // Uses approximate calendar math (365d/year, 30d/month). See #23.
 
+import { Temporal } from "temporal-polyfill";
+
 export function addDuration(baseIso: string, duration: string): string {
   const pattern = /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/;
   const match = duration.match(pattern);

package/src/engine/steps/unsafe-projection-upsert.ts

@@ -11,6 +11,7 @@
 // rejected by boot-validation — domain mutation MUST go through
 // r.step.aggregate.*.
 
+import { KUMIKO_COLUMNS_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { extractTableName } from "../../db";
 import { executeRawQuery } from "../../db/queries/raw-sql";
 import { defineStep } from "../define-step";
@@ -23,10 +24,6 @@ type UnsafeProjectionUpsertArgs = {
   readonly row: StepResolver<Record<string, unknown>>;
 };
 
-// @cast-boundary drizzle-bridge — reads column snake_case names from
-// drizzle Symbol-based metadata without importing drizzle-orm.
-const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
-
 function resolveColumnName(table: unknown, field: string): string {
   if (typeof table !== "object" || table === null) return field;
   const cols = (table as Record<symbol, unknown>)[KUMIKO_COLUMNS_SYMBOL];

package/src/engine/types/config.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/config";
+export type * from "@cosmicdrift/kumiko-types/config";

package/src/engine/types/define-handler.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/define-handler";
+export type * from "@cosmicdrift/kumiko-types/define-handler";

package/src/engine/types/entity-handlers.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/entity-handlers";
+export type * from "@cosmicdrift/kumiko-types/entity-handlers";

package/src/engine/types/event-type-map.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/event-type-map";
+export type * from "@cosmicdrift/kumiko-types/event-type-map";

package/src/engine/types/feature.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/feature";
+export type * from "@cosmicdrift/kumiko-types/feature";

package/src/engine/types/fields.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/fields";
+export type * from "@cosmicdrift/kumiko-types/fields";

package/src/engine/types/handlers.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/handlers";
+export type * from "@cosmicdrift/kumiko-types/handlers";

package/src/engine/types/hooks.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/hooks";
+export type * from "@cosmicdrift/kumiko-types/hooks";

package/src/engine/types/http-route.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/http-route";
+export type * from "@cosmicdrift/kumiko-types/http-route";

package/src/engine/types/nav.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/nav";
+export type * from "@cosmicdrift/kumiko-types/nav";

package/src/engine/types/ownership.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/ownership";
+export type * from "@cosmicdrift/kumiko-types/ownership";

package/src/engine/types/projection.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/projection";
+export type * from "@cosmicdrift/kumiko-types/projection";

package/src/engine/types/relations.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/relations";
+export type * from "@cosmicdrift/kumiko-types/relations";

package/src/engine/types/screen.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/screen";
+export type * from "@cosmicdrift/kumiko-types/screen";

package/src/engine/types/step.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/step";
+export type * from "@cosmicdrift/kumiko-types/step";

package/src/engine/types/target-ref.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/target-ref";
+export type * from "@cosmicdrift/kumiko-types/target-ref";

package/src/engine/types/tree-node.ts

@@ -1 +1 @@
-export * from "@cosmicdrift/kumiko-types/tree-node";
+export type * from "@cosmicdrift/kumiko-types/tree-node";

package/src/engine/types/workspace.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/workspace";
+export type * from "@cosmicdrift/kumiko-types/workspace";

package/src/engine/validate-projection-allowlist.ts

@@ -23,6 +23,10 @@
 // caught by this validator. A future lint-rule will enforce the contract
 // statically; today it lives in this comment + the StepBuilder doc.
 
+import {
+  KUMIKO_META_SYMBOL,
+  KUMIKO_NAME_SYMBOL,
+} from "@cosmicdrift/kumiko-types/schema-table-types";
 import { getStep } from "./define-step";
 import { buildPipelineSteps } from "./pipeline";
 import type { FeatureDefinition, SessionUser, TenantId, WriteEvent } from "./types";
@@ -55,13 +59,9 @@ function* walkAllSteps(steps: readonly StepInstance[]): Generator<StepInstance,
   }
 }
 
-// @cast-boundary drizzle-bridge — reads table name from a Symbol without
-// importing drizzle-orm (bun-db pattern, see bun-db/query.ts).
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
 // table()/buildEntityTable spread column handles as enumerable props, so an
 // entity field named `tableName`/`source` would shadow the matching meta key —
-// the canonical meta under this symbol is the only collision-safe source.
-const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
+// the canonical meta under KUMIKO_META_SYMBOL is the only collision-safe source.
 
 function resolveTableNameFromStep(table: unknown): string {
   if (typeof table === "object" && table !== null) {
@@ -71,7 +71,7 @@ function resolveTableNameFromStep(table: unknown): string {
       const metaName = (meta as Record<string, unknown>)["tableName"];
       if (typeof metaName === "string") return metaName;
     }
-    // Plain meta (buildEntityTableMeta / defineUnmanagedTable — no handle-spread).
+    // Plain meta (deriveEntityTableMeta / defineUnmanagedTable — no handle-spread).
     if (
       "source" in table &&
       "tableName" in table &&

package/src/errors/classes.ts

@@ -138,6 +138,27 @@ export class VersionConflictError extends ConflictError {
   }
 }
 
+// The caller retried a write with an idempotencyKey it had already used —
+// the event-store's partial unique index on metadata.idempotencyKey caught
+// the duplicate. Distinct from unique_violation/version_conflict: this is
+// not an error the caller should retry, it means the earlier attempt
+// already succeeded and this one is a no-op replay.
+export class IdempotentReplayError extends ConflictError {
+  override readonly code: string = "idempotent_replay";
+
+  constructor(
+    details: { readonly idempotencyKey: string },
+    opts?: Pick<ErrorOpts, "i18nKey" | "cause">,
+  ) {
+    super({
+      message: `event with idempotencyKey "${details.idempotencyKey}" was already appended`,
+      i18nKey: opts?.i18nKey ?? "errors.idempotentReplay",
+      details,
+      ...(opts?.cause && { cause: opts.cause }),
+    });
+  }
+}
+
 // Entity-level unique-index violation. Distinct from VersionConflictError:
 // version_conflict means "two writers raced on the events_aggregate_version
 // _uq index" (optimistic-concurrency); unique_violation means "you tried to

package/src/errors/index.ts

@@ -13,6 +13,7 @@ export {
   AccessDeniedError,
   ConflictError,
   FeatureDisabledError,
+  IdempotentReplayError,
   InternalError,
   NotFoundError,
   RateLimitError,

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

@@ -7,8 +7,12 @@ import { KumikoError } from "./kumiko-error";
 import { FrameworkReasons } from "./reasons";
 import { buildInvalidTransitionDetails } from "./transition-details";
 
-// Legacy types — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/write-error-info-types";
+// Re-exported so a caller importing this module directly (instead of via
+// the `./errors` barrel, which already re-exports these by name) still
+// gets the types — explicit, not a wildcard: this module isn't a public
+// subpath export (see package.json `exports`), so the only readers are
+// framework-internal.
+export type { WriteErrorInfo, WriteFailure };
 
 // Convenience for call sites that return a failed WriteResult. Keeps the
 // pattern `return writeFailure(new NotFoundError(...))` compact so handlers

package/src/event-store/__tests__/admin-api.integration.test.ts

@@ -15,7 +15,7 @@ import { asRawClient, selectMany } from "../../db/query";
 import { createTestDb, type TestDb } from "../../stack";
 import { generateId as uuid } from "../../utils";
 import { appendRaw, appendRawBatch, type RawEventToAppend } from "../admin-api";
-import { VersionConflictError } from "../errors";
+import { IdempotentAppendConflictError, VersionConflictError } from "../errors";
 import { append, loadAggregate } from "../event-store";
 import { createEventsTable, eventsTable } from "../events-schema";
 
@@ -187,6 +187,32 @@ describe("appendRaw — single event", () => {
     ).rejects.toBeInstanceOf(VersionConflictError);
   });
 
+  test("appendRaw distinguishes an idempotency-key replay from a version conflict (#1499)", async () => {
+    const idempotencyKey = uuid();
+    await appendRaw(
+      testDb.db,
+      makeEvent({
+        aggregateId: uuid(),
+        expectedVersion: 0,
+        metadata: { userId: userMigration, idempotencyKey },
+      }),
+    );
+
+    // A second, different aggregate reusing the same idempotencyKey hits
+    // the tenant-scoped partial unique index — distinct from a version
+    // race on the same aggregate, and must not be reported as one.
+    await expect(
+      appendRaw(
+        testDb.db,
+        makeEvent({
+          aggregateId: uuid(),
+          expectedVersion: 0,
+          metadata: { userId: userMigration, idempotencyKey },
+        }),
+      ),
+    ).rejects.toBeInstanceOf(IdempotentAppendConflictError);
+  });
+
   test("version_conflict on missing predecessor (appendRaw v=5 without v=1..4)", async () => {
     const aggregateId = uuid();
     // Try to write version=5 (expectedVersion=4) against an empty stream.