@cosmicdrift/kumiko-framework 0.14.0 → 0.16.0

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

@@ -5,8 +5,8 @@
 // pinned by parse.test.ts + render-roundtrip.test.ts) so a failure
 // here narrows the cause to patch.ts itself.
 
+import { describe, expect, test } from "bun:test";
 import { Project, type SourceFile } from "ts-morph";
-import { describe, expect, test } from "vitest";
 import { parseSourceFile } from "../parse";
 import { addPattern, applyChanges, type PatternId, removePattern, replacePattern } from "../patch";
 import { createFeaturePatcher } from "../patcher";

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

@@ -8,8 +8,8 @@
 // arg layout the AI/Designer provides and creates a syntactically valid
 // pattern.
 
+import { describe, expect, test } from "bun:test";
 import { Project, type SourceFile } from "ts-morph";
-import { describe, expect, test } from "vitest";
 import { parseSourceFile } from "../parse";
 import { createFeaturePatcher } from "../patcher";
 

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

@@ -8,8 +8,8 @@
 // (where the pattern came from) and the rendered file (where it ends
 // up at canonical positions). We compare every other field.
 
+import { describe, expect, test } from "bun:test";
 import { Project } from "ts-morph";
-import { describe, expect, test } from "vitest";
 import { parseSourceFile } from "../parse";
 import type { FeaturePattern } from "../patterns";
 import { renderFeatureFile, renderPattern } from "../render";

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

@@ -7,8 +7,8 @@
 // AST extractor + the Designer/AI consumers (renderPattern,
 // getEditability, PATTERN_LIBRARY). Both halves must agree on shape.
 
+import { describe, expect, test } from "bun:test";
 import { Project } from "ts-morph";
-import { describe, expect, test } from "vitest";
 import { parseSourceFile } from "../parse";
 import { getEditability } from "../patterns";
 import { renderPattern } from "../render";

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

@@ -1,5 +1,6 @@
 import type { CallExpression, Node } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
+import { isPlainObject } from "../../../utils/is-plain-object";
 import type { ParseError } from "../parse";
 
 export type ExtractOutput<TPattern> =
@@ -107,9 +108,7 @@ export function readDataLiteralNode(node: Node): unknown {
   }
 }
 
-export function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+export { isPlainObject } from "../../../utils/is-plain-object";
 
 export function readPropertyKey(propAssign: import("ts-morph").PropertyAssignment): string {
   const nameNode = propAssign.getNameNode();

package/src/engine/ownership.ts

@@ -12,14 +12,22 @@
 //   { from: "claim:<featureQn>",
 //     column?: "..." }                   → row[column ?? claim.shortName] === user.claims[claim.qn]
 //                                         (string[] claim → inArray)
-//   { where: (user, table) => SQL }      → escape hatch, arbitrary Drizzle predicate
+//   { where: (user, ctx) => SqlFragment } → escape hatch, raw parameterised SQL
 //
 // Construction: use the `from(ref, column?)` helper. It returns a FromRule
 // ready to drop into an access map.
 
-import { eq, inArray, or, type SQL, sql } from "drizzle-orm";
+import { toSnakeCase } from "../db/table-builder";
 import type { SessionUser } from "./types";
 
+// Parameterised SQL fragment — produced by buildOwnershipClause + by the
+// WhereRule escape-hatch. Caller weaves `sqlText` into a larger statement,
+// renumbering placeholders if needed (FragmentBuilder below).
+export type SqlFragment = {
+  readonly sqlText: string;
+  readonly params: readonly unknown[];
+};
+
 // Reference spec supported by `from()`:
 //   "user:id"                  → user.id
 //   "user:tenantId"            → user.tenantId (rarely needed — TenantDb scopes anyway)
@@ -49,9 +57,18 @@ export type FromRule = {
   readonly column: string;
 };
 
+// Context passed to a WhereRule escape-hatch. The author returns a SqlFragment
+// whose placeholders start at `paramStart` ($N, $N+1, ...); the framework
+// concatenates the fragment into the larger query.
+export type WhereRuleContext<TTable = unknown> = {
+  readonly table: TTable;
+  readonly tableName: string;
+  readonly paramStart: number;
+};
+
 export type WhereRule<TTable = unknown> = {
   readonly kind: "where";
-  readonly where: (user: SessionUser, table: TTable) => SQL;
+  readonly where: (user: SessionUser, ctx: WhereRuleContext<TTable>) => SqlFragment;
 };
 
 // "all" collapses to a primitive so map authors can write `Admin: "all"`
@@ -244,51 +261,94 @@ export function userCanCreateFieldRow(
 //   "empty" → user has a role mapped but no rule accepts any row (missing
 //             claim, empty array, role not in map). Skip the DB call entirely
 //             — returning [] is equivalent and avoids a pointless roundtrip.
-//   "sql"   → apply `.sql` as an AND to the query's where clause.
+//   "sql"   → apply the parameterised fragment as an AND on the query.
+//             Caller is responsible for renumbering placeholders when
+//             concatenating with other fragments (see `shiftParams` below).
 //
 // "empty" vs. "pass" is the critical distinction for a safe default:
-// undefined/pass = allow, empty = deny-by-construction. Mixing them up was
-// the exact leak direction advisor flagged; the disjoint type prevents it.
+// undefined/pass = allow, empty = deny-by-construction.
 export type OwnershipClause =
   | { readonly kind: "pass" }
   | { readonly kind: "empty" }
-  | { readonly kind: "sql"; readonly sql: SQL };
+  | { readonly kind: "sql"; readonly sqlText: string; readonly params: readonly unknown[] };
 
 const PASS_CLAUSE: OwnershipClause = { kind: "pass" };
 const EMPTY_CLAUSE: OwnershipClause = { kind: "empty" };
 
-// Build an ownership clause for entity-level READ access. The caller
-// translates the result to its query layer (see above).
+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];
+    if (typeof sym === "string") return sym;
+  }
+  return "<unknown>";
+}
+
+// Resolve a JS-field name on the table to its underlying SQL column name.
+// Drizzle tables carry the mapping under Symbol.for("kumiko:schema:Columns");
+// we read it without importing drizzle-orm at runtime.
+function columnSqlName(table: unknown, field: string): string | null {
+  if (table === null || typeof table !== "object") return null;
+  const cols = (table as Record<symbol, unknown>)[KUMIKO_COLUMNS_SYMBOL];
+  if (cols && typeof cols === "object") {
+    const col = (cols as Record<string, unknown>)[field];
+    if (col && typeof col === "object") {
+      const nameVal = (col as Record<string, unknown>)["name"];
+      if (typeof nameVal === "string") return nameVal;
+    }
+  }
+  // Field may already be the SQL column name on plain objects (tests, etc.).
+  if ((table as Record<string, unknown>)[field] !== undefined) {
+    return toSnakeCase(field);
+  }
+  return null;
+}
+
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+// Shift `$N` placeholder numbers in an embedded fragment so they line up
+// with the outer query's param array.
+export function shiftParams(fragment: SqlFragment, shift: number): SqlFragment {
+  if (shift === 0) return fragment;
+  const sqlText = fragment.sqlText.replace(/\$(\d+)/g, (_, num) => `$${Number(num) + shift}`);
+  return { sqlText, params: fragment.params };
+}
+
+// Build an ownership clause for entity-level READ access. Caller weaves
+// the result into a raw-SQL WHERE (see event-store-executor list/getById).
 //
-// `table` is the Drizzle table with column objects. Unknown column on a
-// from-rule is a boot-time misconfiguration; at request time we treat it
-// as empty (safe default) rather than passing silently.
+// `table` is the (drizzle or compatible) table object; we extract column
+// SQL names via the kumiko:schema:Columns symbol. Unknown column on a from-rule
+// is a boot-time misconfiguration; at request time we treat it as empty
+// (safe default) rather than passing silently.
 export function buildOwnershipClause(
   user: SessionUser,
   accessMap: OwnershipMap | undefined,
-  // biome-ignore lint/suspicious/noExplicitAny: Drizzle tables carry schema-dependent column shapes
-  table: any,
+  table: unknown,
+  paramStart = 1,
 ): OwnershipClause {
   if (!accessMap || Object.keys(accessMap).length === 0) return PASS_CLAUSE;
 
-  const clauses: SQL[] = [];
+  const clauses: SqlFragment[] = [];
   let anyRoleMatched = false;
   let everyRuleCollapsedToEmpty = true;
+  let nextParamIdx = paramStart;
 
   for (const role of user.roles) {
     const rule = accessMap[role];
     if (!rule) continue;
     anyRoleMatched = true;
-    // "all" = no filter at all for this role; short-circuit.
     if (rule === "all") return PASS_CLAUSE;
-    const resolved = ruleToClause(rule, user, table);
+    const resolved = ruleToFragment(rule, user, table, nextParamIdx);
     if (resolved.kind === "sql") {
-      clauses.push(resolved.sql);
+      clauses.push({ sqlText: resolved.sqlText, params: resolved.params });
+      nextParamIdx += resolved.params.length;
       everyRuleCollapsedToEmpty = false;
     }
-    // "empty" contribution from one role doesn't short-circuit: another
-    // role might still contribute an OR-branch. But if ALL branches are
-    // empty, the result is empty.
   }
 
   if (!anyRoleMatched) return EMPTY_CLAUSE;
@@ -296,42 +356,54 @@ export function buildOwnershipClause(
   if (clauses.length === 1) {
     const only = clauses[0];
     if (!only) return EMPTY_CLAUSE;
-    return { kind: "sql", sql: only };
+    return { kind: "sql", sqlText: `(${only.sqlText})`, params: only.params };
   }
-  // @cast-boundary db-operator — drizzle or() widened signature
-  // biome-ignore lint/suspicious/noExplicitAny: same reason as above
-  const combined = or(...(clauses as any)) as SQL;
-  return { kind: "sql", sql: combined };
+  const sqlText = clauses.map((c) => `(${c.sqlText})`).join(" OR ");
+  const params: unknown[] = [];
+  for (const c of clauses) for (const p of c.params) params.push(p);
+  return { kind: "sql", sqlText: `(${sqlText})`, params };
 }
 
-type RuleClauseResult = { readonly kind: "empty" } | { readonly kind: "sql"; readonly sql: SQL };
+type RuleFragmentResult =
+  | { readonly kind: "empty" }
+  | { readonly kind: "sql"; readonly sqlText: string; readonly params: readonly unknown[] };
 
-function ruleToClause(
+function ruleToFragment(
   rule: OwnershipRule,
   user: SessionUser,
-  // biome-ignore lint/suspicious/noExplicitAny: Drizzle tables carry schema-dependent column shapes
-  table: any,
-): RuleClauseResult {
+  table: unknown,
+  paramStart: number,
+): RuleFragmentResult {
   if (rule === "all") {
-    // Caller handles "all" by short-circuit before reaching here; defensive
-    // fallback.
-    return { kind: "sql", sql: sql`true` };
+    return { kind: "sql", sqlText: "TRUE", params: [] };
   }
   if (rule.kind === "where") {
-    return { kind: "sql", sql: rule.where(user, table) };
+    const frag = rule.where(user, {
+      table,
+      tableName: tableNameOf(table),
+      paramStart,
+    });
+    return { kind: "sql", sqlText: frag.sqlText, params: frag.params };
   }
   // FromRule
-  const column = table[rule.column];
-  // Unknown column — boot validator should have caught this, but at request
-  // time we treat as empty (fail-closed).
-  if (!column) return { kind: "empty" };
+  const colName = columnSqlName(table, rule.column);
+  if (!colName) return { kind: "empty" };
 
   const value = resolveUserValue(rule, user);
   if (value === undefined || value === null) return { kind: "empty" };
 
   if (Array.isArray(value)) {
     if (value.length === 0) return { kind: "empty" };
-    return { kind: "sql", sql: inArray(column, value) };
+    const placeholders = value.map((_, i) => `$${paramStart + i}`).join(", ");
+    return {
+      kind: "sql",
+      sqlText: `${quoteIdent(colName)} IN (${placeholders})`,
+      params: value,
+    };
   }
-  return { kind: "sql", sql: eq(column, value) };
+  return {
+    kind: "sql",
+    sqlText: `${quoteIdent(colName)} = $${paramStart}`,
+    params: [value],
+  };
 }

package/src/engine/pattern-library/__tests__/library.test.ts

@@ -7,7 +7,7 @@
 //      sample pattern (sanity check that entity-fields-editor points at
 //      `definition.fields`, not `fields`).
 
-import { describe, expect, expectTypeOf, test } from "vitest";
+import { describe, expect, expectTypeOf, test } from "bun:test";
 import {
   type FeaturePattern,
   type FeaturePatternKind,
@@ -24,7 +24,7 @@ import {
 // All FeaturePatternKind discriminator values, hand-listed so the test
 // fails CI when a new pattern is added without a library entry. Match
 // against the FeaturePattern union via type-test below.
-const ALL_KINDS: readonly FeaturePatternKind[] = [
+const ALL_KINDS: FeaturePatternKind[] = [
   "requires",
   "optionalRequires",
   "readsConfig",

package/src/engine/projection-helpers.ts

@@ -1,5 +1,5 @@
-import { eq } from "drizzle-orm";
 import type { DbRunner } from "../db/connection";
+import { updateMany } from "../db/query";
 import type { StoredEvent } from "../event-store/event-store";
 import type { MultiStreamApplyContext } from "../pipeline/multi-stream-apply-context";
 import type { MultiStreamApplyFn, ProjectionTable, SingleStreamApplyFn } from "./types/projection";
@@ -71,15 +71,6 @@ export function setFields(
   }
   return async (event, tx) => {
     const values = typeof fields === "function" ? fields(event) : fields;
-    // ProjectionTable erases its column shape on purpose (the framework
-    // does not know user table shapes). Drizzle's tx.update().set() is
-    // strict about the concrete row, so we feed it the erased value; the
-    // type-safety guarantee for `values` lives at the setFields call-site.
-    // biome-ignore lint/suspicious/noExplicitAny: see note above.
-    const set = values as any; // @cast-boundary engine-bridge
-    await tx
-      .update(table)
-      .set(set)
-      .where(eq(idCol as never, event.aggregateId)); // @cast-boundary db-operator
+    await updateMany(tx, table, values, { id: event.aggregateId });
   };
 }

package/src/engine/registry.ts

@@ -1,5 +1,5 @@
 import { applyEntityEvent } from "../db/apply-entity-event";
-import { buildDrizzleTable } from "../db/table-builder";
+import { buildEntityTable } from "../db/table-builder";
 import { buildMetricName, validateMetricName } from "../observability";
 import { type QnType, qualifyEntityName } from "./qualified-name";
 import type {
@@ -40,6 +40,7 @@ import type {
   TranslationKeys,
   TreeActionDef,
   TreeChildrenSubscribe,
+  UnmanagedTableDef,
   WorkspaceDefinition,
   WriteHandlerDef,
 } from "./types";
@@ -67,7 +68,7 @@ function buildImplicitProjection(
   qualify: typeof qualifyEntityName,
 ): ProjectionDefinition {
   const name = qualify(featureName, "projection", `${entityName}${IMPLICIT_PROJECTION_SUFFIX}`);
-  const drizzleTable = buildDrizzleTable(entityName, entity);
+  const drizzleTable = buildEntityTable(entityName, entity);
   // applyEntityEvent gibt ApplyResult zurück; SingleStreamApplyFn erwartet
   // Promise<void>. Im rebuild-Pfad ist die Row irrelevant — wir discarden.
   const handler = async (
@@ -169,6 +170,10 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   // enforced at ingest below (collisions would race two CREATE TABLE
   // statements at the same physical name and break boot).
   const rawTableMap = new Map<string, RawTableDef>();
+  // Unmanaged tables — declared via r.unmanagedTable() (EntityTableMeta).
+  // Cousin of rawTables: same uniqueness-by-tableName invariant, different
+  // storage shape (post-drizzle migrate-runner consumes EntityTableMeta).
+  const unmanagedTableMap = new Map<string, UnmanagedTableDef>();
   // Auth-claims hooks — tagged with featureName so the login resolver can
   // auto-prefix each hook's returned keys with "<feature>:".
   const authClaimsHooks: AuthClaimsHookDef[] = [];
@@ -543,6 +548,20 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
       rawTableMap.set(rawName, { ...rawDef, featureName: feature.name });
     }
 
+    // Unmanaged tables — same cross-feature uniqueness invariant as rawTables.
+    // Two features registering the same physical tableName would race two
+    // CREATE TABLE statements via migrate-runner.
+    for (const [umName, umDef] of Object.entries(feature.unmanagedTables ?? {})) {
+      const existing = unmanagedTableMap.get(umName);
+      if (existing) {
+        throw new Error(
+          `Unmanaged-table "${umName}" registered by both feature "${existing.featureName}" and ` +
+            `"${feature.name}". Pick a feature-prefixed tableName to disambiguate.`,
+        );
+      }
+      unmanagedTableMap.set(umName, { ...umDef, featureName: feature.name });
+    }
+
     // Claim keys: aggregated by qualified name. Two features cannot collide
     // here (qualified by feature name), but we still guard for explicit
     // correctness — the only way to hit this is a hand-built FeatureDefinition

package/src/engine/steps/read-find-many.ts

@@ -1,24 +1,22 @@
 // r.step.read.findMany — load multiple rows from a projection table.
 //
-// Sibling to read.findOne — same tenant-filter caveat (caller-owned),
-// same drizzle-boundary cast. Resolves to a row-array (possibly empty),
-// landed under steps.<name>.
+// Sibling to read.findOne — same tenant-filter caveat (caller-owned).
+// Resolves to a row-array (possibly empty), landed under steps.<name>.
 //
 // Optional `limit` — defaults to no-limit (caller-chosen, NOT a
 // guard-rail). Most legitimate uses iterate via r.step.forEach (M.1.6)
 // over the result, where unbounded arrays would be the bug. Set
 // `limit` explicitly when the row-count could grow without bound.
 
-import type { SQL, Table } from "drizzle-orm";
+import { selectMany, type WhereObject } from "../../db/query";
 import { defineStep } from "../define-step";
 import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
-import { asQueryTarget } from "./_drizzle-boundary";
 import { resolveOptional } from "./_resolver-utils";
 
 type ReadFindManyArgs = {
   readonly name: string;
-  readonly table: Table;
-  readonly where?: StepResolver<SQL | undefined>;
+  readonly table: unknown;
+  readonly where?: StepResolver<WhereObject | undefined>;
   readonly limit?: number;
 };
 
@@ -28,10 +26,12 @@ defineStep<ReadFindManyArgs, readonly Record<string, unknown>[]>({
   resultKey: (args) => args.name,
   run: async (args, ctx: PipelineCtx) => {
     const where = resolveOptional(args.where, ctx);
-    const baseQuery = ctx.db.select().from(asQueryTarget(args.table));
-    const filteredQuery = where === undefined ? baseQuery : baseQuery.where(where);
-    const finalQuery = args.limit === undefined ? filteredQuery : filteredQuery.limit(args.limit);
-    const rows = await finalQuery;
+    const rows = await selectMany(
+      ctx.db.raw,
+      args.table,
+      where,
+      args.limit !== undefined ? { limit: args.limit } : undefined,
+    );
     return rows as readonly Record<string, unknown>[];
   },
 });
@@ -39,8 +39,8 @@ defineStep<ReadFindManyArgs, readonly Record<string, unknown>[]>({
 export function buildReadFindManyStep(
   name: string,
   opts: {
-    readonly table: Table;
-    readonly where?: StepResolver<SQL | undefined>;
+    readonly table: unknown;
+    readonly where?: StepResolver<WhereObject | undefined>;
     readonly limit?: number;
   },
 ): StepInstance {

package/src/engine/steps/read-find-one.ts

@@ -1,6 +1,6 @@
 // r.step.read.findOne — load a single row from a projection table.
 //
-// Thin wrapper on ctx.db.select().from(table).where(where).limit(1).
+// Thin wrapper on selectMany(db, table, where, { limit: 1 }) (bun-db).
 // Resolves to the first row or null. Tenant-isolation: the caller's
 // `where` clause is responsible for any tenantId filter — read.findOne
 // does NOT auto-inject one (different from ctx.queryProjection which
@@ -20,16 +20,15 @@
 // fine for "find by uuid", a footgun for "find by tenantId". No
 // runtime check; reviewer responsibility.
 
-import type { SQL, Table } from "drizzle-orm";
+import { selectMany, type WhereObject } from "../../db/query";
 import { defineStep } from "../define-step";
 import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
-import { asQueryTarget } from "./_drizzle-boundary";
 import { resolveRequired } from "./_resolver-utils";
 
 type ReadFindOneArgs = {
   readonly name: string;
-  readonly table: Table;
-  readonly where: StepResolver<SQL | undefined>;
+  readonly table: unknown;
+  readonly where: StepResolver<WhereObject | undefined>;
 };
 
 defineStep<ReadFindOneArgs, Record<string, unknown> | null>({
@@ -38,8 +37,7 @@ defineStep<ReadFindOneArgs, Record<string, unknown> | null>({
   resultKey: (args) => args.name,
   run: async (args, ctx: PipelineCtx) => {
     const where = resolveRequired(args.where, ctx);
-    const query = ctx.db.select().from(asQueryTarget(args.table));
-    const rows = where === undefined ? await query.limit(1) : await query.where(where).limit(1);
+    const rows = await selectMany(ctx.db.raw, args.table, where, { limit: 1 });
     return (rows[0] as Record<string, unknown> | undefined) ?? null;
   },
 });
@@ -47,8 +45,8 @@ defineStep<ReadFindOneArgs, Record<string, unknown> | null>({
 export function buildReadFindOneStep(
   name: string,
   opts: {
-    readonly table: Table;
-    readonly where: StepResolver<SQL | undefined>;
+    readonly table: unknown;
+    readonly where: StepResolver<WhereObject | undefined>;
   },
 ): StepInstance {
   return {

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

@@ -16,10 +16,9 @@
 // must commit in the same TX as the aggregate-mutation that triggered
 // it (stronger consistency than an async projection). Reviewer judges.
 
-import type { SQL, Table } from "drizzle-orm";
+import { deleteMany, type WhereObject } from "../../db/query";
 import { defineStep } from "../define-step";
 import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
-import { asQueryTarget } from "./_drizzle-boundary";
 import { resolveRequired } from "./_resolver-utils";
 
 // `where` is REQUIRED — table-wide DELETE without a clause is a TRUNCATE
@@ -28,8 +27,8 @@ import { resolveRequired } from "./_resolver-utils";
 // `r.step.unsafeProjectionTruncate` step rather than loosening this
 // type to `SQL | undefined`.
 type UnsafeProjectionDeleteArgs = {
-  readonly table: Table;
-  readonly where: StepResolver<SQL>;
+  readonly table: unknown;
+  readonly where: StepResolver<WhereObject>;
 };
 
 defineStep<UnsafeProjectionDeleteArgs, void>({
@@ -37,7 +36,7 @@ defineStep<UnsafeProjectionDeleteArgs, void>({
   defaultFailureStrategy: "throw",
   run: async (args, ctx: PipelineCtx) => {
     const where = resolveRequired(args.where, ctx);
-    await ctx.db.delete(asQueryTarget(args.table)).where(where);
+    await deleteMany(ctx.db.raw, args.table, where);
   },
 });