@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/agents/examples/relations.md

@@ -38,7 +38,12 @@ bun test
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
-import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  attachOutsideTransaction,
+  bridgeStub,
+  type HandlerContext,
+  type SaveContext,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createCascadeDeleteHook } from "@cosmicdrift/kumiko-framework/pipeline";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
@@ -77,6 +82,16 @@ beforeEach(() => {
   stack.events.reset();
 });
 
+// The cascade hook runs against the same tenant-scoped db a dispatcher would hand it.
+function hookContext(): HandlerContext {
+  const db = createTenantDb({ db: stack.db, tenantId: admin.tenantId });
+  return {
+    ...bridgeStub({ user: admin }),
+    registry: stack.registry,
+    db: attachOutsideTransaction(db, undefined),
+  };
+}
+
 describe("restrict: team cannot be deleted with members", () => {
   test("delete team with members fails", async () => {
     const team = await stack.http.writeOk<SaveContext>(
@@ -105,7 +120,7 @@ describe("restrict: team cannot be deleted with members", () => {
           entityName: "team",
           event: createTestStoredEvent(),
         },
-        { db: stack.db },
+        hookContext(),
       ),
     ).rejects.toMatchObject({ code: "conflict", details: { reason: "delete_restricted" } });
   });
@@ -128,7 +143,7 @@ describe("restrict: team cannot be deleted with members", () => {
           entityName: "team",
           event: createTestStoredEvent(),
         },
-        { db: stack.db },
+        hookContext(),
       ),
     ).resolves.toBeUndefined();
   });
@@ -178,7 +193,7 @@ describe("cascade: deleting member removes tasks", () => {
         entityName: "member",
         event: createTestStoredEvent(),
       },
-      { db: createTenantDb({ db: stack.db, tenantId: admin.tenantId }) },
+      hookContext(),
     );
 
     // Tasks should be gone

package/agents/examples/search.md

@@ -13,7 +13,7 @@ Tenant-scoped full-text search (Meilisearch / in-memory adapter).
 ## What it shows
 
 - `searchable` / `searchWeight` on fields
-- Handler reads via `ctx.searchAdapter`
+- Handler reads via `ctx.services.searchAdapter`
 
 ## Source
 
@@ -160,7 +160,7 @@ describe("search indexing", () => {
 ```ts
 // Search Sample
 // Shows: searchable fields, searchWeight, search via InMemory SearchAdapter.
-// Each handler builds its executor inline so `ctx.searchAdapter` is read fresh
+// Each handler builds its executor inline so `ctx.services.searchAdapter` is read fresh
 // per call — tests swap the adapter between runs.
 
 import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
@@ -198,7 +198,7 @@ export const productFeature = defineFeature("shop", (r) => {
     }),
     handler: async (event, ctx) => {
       const crud = createEventStoreExecutor(productTable, productEntity, {
-        searchAdapter: ctx.searchAdapter,
+        searchAdapter: ctx.services.searchAdapter,
         entityName: "product",
       });
       return crud.create(event.payload, event.user, ctx.db);
@@ -214,7 +214,7 @@ export const productFeature = defineFeature("shop", (r) => {
     }),
     handler: async (query, ctx) => {
       const crud = createEventStoreExecutor(productTable, productEntity, {
-        searchAdapter: ctx.searchAdapter,
+        searchAdapter: ctx.services.searchAdapter,
         entityName: "product",
       });
       return crud.list(query.payload, query.user, ctx.db);

package/agents/examples/secrets-demo.md

@@ -12,7 +12,7 @@ Tenant-owned secrets with envelope encryption, DEK cache, and KEK rotation.
 
 ## What it shows
 
-- `r.secret` + `ctx.secrets.get` (audited reads)
+- `r.secret` + `ctx.services.secrets.get` (audited reads)
 - Charge-style handler that never returns the plaintext key
 
 ## Source
@@ -39,7 +39,7 @@ bun test
 // function calls into framework internals):
 //   1. A TenantAdmin sets a secret over HTTP → DB holds only an envelope.
 //   2. list handler returns a redacted preview, never plaintext.
-//   3. Feature code (ctx.secrets.get) decrypts through the audited wrapper.
+//   3. Feature code (ctx.services.secrets.get) decrypts through the audited wrapper.
 //      Every read writes a tenantSecretRead event to the events-table.
 //   4. The response-guard catches accidental Secret<> leaks: a handler
 //      that tries to return the branded value triggers a 500 at the
@@ -129,7 +129,7 @@ beforeAll(async () => {
     features: [createJobsFeature(), createSecretsFeature(), createBillingFeature(), leakyFeature],
     // Typed masterKeyProvider option: lands in AppContext as a typed field,
     // no Record<string, unknown>-via-extraContext. The rotation job reads
-    // it from ctx.masterKeyProvider directly.
+    // it from ctx.services.masterKeyProvider directly.
     masterKeyProvider: providerRef,
     extraContext: ({ db, registry }) => ({
       // SecretsContext sees the mutable ref — any replace() flips what
@@ -299,7 +299,7 @@ describe("5. KEK rotation via the core job + real BullMQ dispatch", () => {
 
   test("subsequent ctx.secrets.get after rotation still returns the original plaintext", async () => {
     // Goes through the whole real stack: HTTP → dispatcher → billing
-    // handler → ctx.secrets.get → cached DEK-unwrap with V2 → decrypt.
+    // handler → ctx.services.secrets.get → cached DEK-unwrap with V2 → decrypt.
     // If rotation broke anything, fingerprint would differ or the call
     // would throw.
     const result = await stack.http.writeOk<{ keyFingerprint: string }>(
@@ -328,7 +328,7 @@ describe("5. KEK rotation via the core job + real BullMQ dispatch", () => {
 ### src/feature.ts
 
 ```ts
-// A miniature "billing" feature that reads a Stripe API key from ctx.secrets
+// A miniature "billing" feature that reads a Stripe API key from ctx.services.secrets
 // and simulates a charge. The point is to show how feature code uses the
 // plaintext secret without ever exposing it to clients — the charge endpoint
 // returns { chargeId } but never the apiKey.
@@ -357,7 +357,10 @@ const chargeWrite = defineWriteHandler({
   }),
   access: { roles: ["TenantAdmin", "User"] },
   handler: async (event, ctx) => {
-    const secrets = requireSecretsContext(ctx, "billing:write:charge");
+    const secrets = requireSecretsContext(
+      { secrets: ctx.services.secrets, user: ctx.user },
+      "billing:write:charge",
+    );
     // requireSecretsContext returned a wrapper that auto-fills the audit
     // context (userId + "billing:write:charge") on every .get — the read
     // lands in tenant_secret_reads without the handler having to remember.

package/agents/examples/state-machine.md

@@ -492,6 +492,7 @@ export const invoiceTable = buildEntityTable("invoice", invoiceEntity);
 
 import type { EventDef } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { INVOICE_STATES } from "./entities/invoice.ts";
 
 export const FEATURE_NAME = "billing";
 export const ENTITY_NAME = "invoice";
@@ -509,7 +510,7 @@ export const INVOICE_EVENTS = {
 // Qualifier used by the reducer to match events from the stream.
 // `<const TShort>` preserves the literal-string at the call-site, so
 // `eventName(INVOICE_EVENTS.sent)` carries `"billing:event:invoice-sent"`
-// as a literal type. That literal is what `ctx.appendEvent({ type, ... })`
+// as a literal type. That literal is what `ctx.events.append({ type, ... })`
 // strict-checks against the augmented `KumikoEventTypeMap`.
 export function eventName<const TShort extends string>(
   short: TShort,
@@ -523,8 +524,8 @@ export const INVOICE_CREATED_EVENT = `${ENTITY_NAME}.created` as const;
 
 export const emptyEventPayload = z.object({});
 export const statusForcedPayload = z.object({
-  newStatus: z.enum(["draft", "sent", "paid", "cancelled"]),
-  fromStatus: z.enum(["draft", "sent", "paid", "cancelled"]),
+  newStatus: z.enum(INVOICE_STATES),
+  fromStatus: z.enum(INVOICE_STATES),
 });
 
 // The EventDefs r.defineEvent returns inside the feature setup. Handlers receive them so that
@@ -926,7 +927,7 @@ export async function loadInvoiceState(
   ctx: HandlerContext,
   id: string,
 ): Promise<InvoiceState | null> {
-  const events = await ctx.loadAggregate(id);
+  const events = await ctx.events.load(id);
   if (events.length === 0) return null;
   const state: InvoiceState = { ...initialInvoiceState };
   for (const evt of events) reduceInvoice(state, evt);

package/agents/examples/tenant-isolation.md

@@ -13,6 +13,7 @@ Multi-tenant data isolation by default.
 ## What it shows
 
 - Tenant filter on ordinary handlers
+- `ctx.db.upsert`: insert-or-update on a tenant-scoped, non-event-sourced table. `conflictTarget` must contain `tenantId` and match a declared unique index (here `tenant_id, key`); event-fed tables are rejected
 - What breaks if you forget tenancy (and how the framework prevents it)
 
 ## Source
@@ -37,6 +38,7 @@ bun test
 // Proves: tenant_id scopes all data, cross-tenant access returns nothing
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createTestUser, TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
@@ -45,7 +47,7 @@ import {
   type TestStack,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-testing/stack";
-import { noteEntity, noteFeature } from "../feature";
+import { noteEntity, noteFeature, preferenceTable } from "../feature";
 
 let stack: TestStack;
 
@@ -136,12 +138,48 @@ describe("tenant isolation", () => {
     expect(listB.rows.some((r) => r["title"] === "A-Note")).toBe(false);
   });
 });
+
+describe("ctx.db.upsert", () => {
+  const setPreference = (user: typeof tenantBAdmin, key: string, value: string) =>
+    stack.http.writeOk<{ value: string }>("notes:write:preference:set", { key, value }, user);
+
+  test("a second upsert with the same key updates the tenant's row instead of inserting", async () => {
+    await setPreference(tenantAAdmin, "theme", "light");
+    const second = await setPreference(tenantAAdmin, "theme", "dark");
+
+    expect(second.value).toBe("dark");
+    const rows = await selectMany(stack.db, preferenceTable, {
+      tenantId: tenantAAdmin.tenantId,
+      key: "theme",
+    });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["value"]).toBe("dark");
+  });
+
+  test("the same key in another tenant creates a separate row and leaves A's value alone", async () => {
+    await setPreference(tenantAAdmin, "language", "de");
+    await setPreference(tenantBAdmin, "language", "en");
+
+    const rowsA = await selectMany(stack.db, preferenceTable, {
+      tenantId: tenantAAdmin.tenantId,
+      key: "language",
+    });
+    const rowsB = await selectMany(stack.db, preferenceTable, {
+      tenantId: tenantBAdmin.tenantId,
+      key: "language",
+    });
+    expect(rowsA.map((row) => row["value"])).toEqual(["de"]);
+    expect(rowsB.map((row) => row["value"])).toEqual(["en"]);
+  });
+});
 ```
 
 ### src/feature.ts
 
 ```ts
+import { defineUnmanagedTable } from "@cosmicdrift/kumiko-framework/db";
 import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
 
 export const noteEntity = createEntity({
   table: "read_sample_notes",
@@ -151,6 +189,26 @@ export const noteEntity = createEntity({
   },
 });
 
+// Not event-sourced: ctx.db.upsert rejects executor-managed tables.
+export const preferenceTable = defineUnmanagedTable({
+  tableName: "sample_tenant_preferences",
+  columns: [
+    {
+      name: "id",
+      pgType: "uuid",
+      notNull: true,
+      primaryKey: true,
+      defaultSql: "gen_random_uuid()",
+    },
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "key", pgType: "text", notNull: true },
+    { name: "value", pgType: "text", notNull: true },
+  ],
+  indexes: [
+    { name: "sample_tenant_preferences_tenant_key", columns: ["tenant_id", "key"], unique: true },
+  ],
+});
+
 const adminWrite = { access: { roles: ["Admin"] } } as const;
 const openRead = {
   access: {
@@ -168,5 +226,19 @@ export const noteFeature = defineFeature("notes", (r) => {
     read: openRead,
     verbs: { update: false, delete: false, restore: false },
   });
+
+  r.storeTable(preferenceTable, { reason: "settings.tenant_preferences" });
+
+  r.writeHandler({
+    name: "preference:set",
+    schema: z.object({ key: z.string().min(1), value: z.string() }),
+    handler: async (event, ctx) => {
+      const row = await ctx.db.upsert<{ value: string }>(preferenceTable, event.payload, {
+        conflictTarget: ["tenantId", "key"],
+      });
+      return { isSuccess: true, data: { value: row?.value } };
+    },
+    ...adminWrite,
+  });
 });
 ```

package/agents/examples/tenant-settings.md

@@ -158,7 +158,7 @@ beforeAll(async () => {
     features: [createConfigFeature(), createTenantSettingsFeature(), invoiceFeature],
     extraContext: ({ registry }) => ({
       configResolver: resolver,
-      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+      configAccessorFactory: createConfigAccessorFactory(registry, resolver),
     }),
   });
   await unsafePushTables(stack.db, { configValuesTable });

package/agents/examples/user-data-rights.md

@@ -173,7 +173,7 @@ import {
 import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
-import { seedRow } from "@cosmicdrift/kumiko-testing/helpers";
+import { seedRowViaEventStore } from "@cosmicdrift/kumiko-testing/helpers";
 import {
   setupTestStack,
   type TestStack,
@@ -183,8 +183,6 @@ import { noteEntity, notesFeature, notesTable } from "../feature";
 
 let stack: TestStack;
 
-const TENANT_SYSTEM = "00000000-0000-4000-8000-000000000001";
-
 // Each test gets its own tenant and user, so rows from other tests never show up.
 let testNumber = 0;
 let TENANT_A = "";
@@ -231,9 +229,8 @@ function noteId(index: number): string {
 }
 
 async function seedAlice(opts: { gracePeriodEnd?: Instant; status?: string } = {}): Promise<void> {
-  await seedRow(stack.db, userTable, {
+  await seedRowViaEventStore(stack.db, userTable, {
     id: ALICE_ID,
-    tenantId: TENANT_SYSTEM,
     email: ALICE_EMAIL,
     passwordHash: "h",
     displayName: "Alice",
@@ -243,7 +240,7 @@ async function seedAlice(opts: { gracePeriodEnd?: Instant; status?: string } = {
     status: opts.status ?? USER_STATUS.Active,
     gracePeriodEnd: opts.gracePeriodEnd ?? null,
   });
-  await seedRow(stack.db, tenantMembershipsTable, {
+  await seedRowViaEventStore(stack.db, tenantMembershipsTable, {
     tenantId: TENANT_A,
     userId: ALICE_ID,
     roles: '["Member"]',