@cosmicdrift/kumiko-framework 0.146.0 → 0.146.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.146.0",
+  "version": "0.146.2",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -189,7 +189,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.146.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.146.2",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/auth-routes.ts

@@ -2,7 +2,7 @@ import type { Context } from "hono";
 import { Hono } from "hono";
 import { deleteCookie, setCookie } from "hono/cookie";
 import { z } from "zod";
-import { stripForbiddenMembershipRoles } from "../engine/membership-roles";
+import { buildSessionRoles } from "../engine/membership-roles";
 import { createSystemUser } from "../engine/system-user";
 import { type SessionUser, SYSTEM_TENANT_ID, type TenantId } from "../engine/types";
 import { NotFoundError } from "../errors";
@@ -870,13 +870,12 @@ export function createAuthRoutes(
     // tenant A accidentally surviving into tenant B's session). The
     // resolver runs each feature's r.authClaims() hook under the new
     // TenantDb scope.
-    // Strip reserved roles from the membership portion only — globalRoles
+    // buildSessionRoles calls stripForbiddenMembershipRoles internally and
+    // strips reserved roles from the membership side only — globalRoles
     // (where SystemAdmin legitimately lives) is never filtered. Backstop for a
     // membership role that a projection rebuild resurrected past command-time
     // validation (see engine/membership-roles).
-    const mergedRoles = Array.from(
-      new Set([...globalRoles, ...stripForbiddenMembershipRoles(membership.roles)]),
-    );
+    const mergedRoles = buildSessionRoles(globalRoles, membership.roles);
     const targetSession: SessionUser = {
       id: user.id,
       tenantId: targetTenantId,

package/src/db/__tests__/feature-table-sources.test.ts

@@ -0,0 +1,34 @@
+// Regression test for #255-class drift: unmanagedTables must appear in
+// enumerateFeatureTableSources so setupTestStack's auto-push and
+// collectTableMetas see the exact same table set. Before this fix,
+// unmanagedTables were only handled by collectTableMetas directly, so any
+// app relying on setupTestStack's ephemeral DB (Playwright/e2e) never got
+// its unmanaged tables created — e.g. the bundled "sessions" feature's
+// read_user_sessions, breaking every login in an ephemeral test stack.
+
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../../engine/define-feature";
+import { defineUnmanagedTable } from "../entity-table-meta";
+import { enumerateFeatureTableSources } from "../feature-table-sources";
+
+const probeMeta = defineUnmanagedTable({
+  tableName: "ftst_probe",
+  columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
+});
+
+describe("enumerateFeatureTableSources — unmanagedTables", () => {
+  test("includes a feature's unmanagedTable as a table source", () => {
+    const feature = defineFeature("probe", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "direct-write store" });
+    });
+    const sources = enumerateFeatureTableSources(feature);
+    const entry = sources.find((s) => s.origin.includes("ftst_probe"));
+    expect(entry).toBeDefined();
+    expect(entry?.table).toBe(probeMeta);
+  });
+
+  test("a feature with no unmanagedTable contributes nothing extra", () => {
+    const feature = defineFeature("plain", () => {});
+    expect(enumerateFeatureTableSources(feature)).toEqual([]);
+  });
+});

package/src/db/feature-table-sources.ts

@@ -1,7 +1,8 @@
 // Single enumeration of every table-bearing registration on a feature
-// (r.projection, r.multiStreamProjection with table, r.rawTable). Consumed
-// by BOTH the setupTestStack auto-push and collectTableMetas — one list, so
-// test-DB-push and `kumiko schema generate` cannot drift apart again (#255).
+// (r.projection, r.multiStreamProjection with table, r.rawTable,
+// r.unmanagedTable). Consumed by BOTH the setupTestStack auto-push and
+// collectTableMetas — one list, so test-DB-push and `kumiko schema generate`
+// cannot drift apart again (#255).
 // A new table-bearing registrar must be added HERE, not in the consumers.
 
 import type { FeatureDefinition } from "../engine/types";
@@ -31,5 +32,11 @@ export function enumerateFeatureTableSources(
   for (const [name, raw] of Object.entries(feature.rawTables)) {
     sources.push({ table: raw.table, origin: `rawTable "${name}" (${feature.name})` });
   }
+  for (const entry of Object.values(feature.unmanagedTables)) {
+    sources.push({
+      table: entry.meta,
+      origin: `unmanagedTable "${entry.name}" (${feature.name})`,
+    });
+  }
   return sources;
 }

package/src/engine/__tests__/codemod-pipeline.test.ts

@@ -103,14 +103,14 @@ export const myHandler = defineWriteHandler({
 `;
 
 const alreadyPipelineContent = `\
-import { access, defineWriteHandler, pipeline } from "@cosmicdrift/kumiko-framework/engine";
+import { access, defineWriteHandler, stepsPipeline } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 
 export const myHandler = defineWriteHandler({
   name: "test:pipeline",
   schema: z.object({}),
   access: { roles: access.authenticated },
-  perform: pipeline(({ event, r }) => [
+  perform: stepsPipeline(({ event, r }) => [
     r.step.return((ctx) => ({ isSuccess: true, data: { ok: true } })),
   ]),
 });
@@ -173,14 +173,14 @@ describe("analyzeFile", () => {
 
 describe("convertFile", () => {
   describe("static return handler", () => {
-    it("converts handler to perform: pipeline(...)", async () => {
+    it("converts handler to perform: stepsPipeline(...)", async () => {
       const p = writeFixture("static-convert.write.ts", staticReturnContent);
       const result = await convertFile(p);
       expect(result.status).toBe("converted");
       const content = readFileSync(p, "utf8");
-      expect(content).toContain("perform: pipeline");
+      expect(content).toContain("perform: stepsPipeline");
       expect(content).toContain("r.step.return");
-      expect(content).toContain("import { access, defineWriteHandler, pipeline }");
+      expect(content).toContain("import { access, defineWriteHandler, stepsPipeline }");
       expect(content).not.toContain("handler:");
     });
 
@@ -198,7 +198,7 @@ export const h = defineWriteHandler({
       const result = await convertFile(p);
       expect(result.status).toBe("converted");
       const converted = readFileSync(p, "utf8");
-      expect(converted).toContain("pipeline<typeof MySchema, unknown>");
+      expect(converted).toContain("stepsPipeline<typeof MySchema, unknown>");
     });
   });
 
@@ -271,12 +271,12 @@ export const h = defineWriteHandler({
       const result = await convertFile(p);
       expect(result.status).toBe("converted");
       const content = readFileSync(p, "utf8");
-      expect(content).toContain("import { access, defineWriteHandler, pipeline }");
+      expect(content).toContain("import { access, defineWriteHandler, stepsPipeline }");
     });
 
     it("does not duplicate pipeline import when already present", async () => {
       const content = `\
-import { access, defineWriteHandler, pipeline } from "@cosmicdrift/kumiko-framework/engine";
+import { access, defineWriteHandler, stepsPipeline } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 
 export const h = defineWriteHandler({
@@ -288,7 +288,9 @@ export const h = defineWriteHandler({
       const result = await convertFile(p);
       expect(result.status).toBe("converted");
       const final = readFileSync(p, "utf8").split("\n");
-      const pipelineImports = final.filter((l) => l.includes("import") && l.includes("pipeline"));
+      const pipelineImports = final.filter(
+        (l) => l.includes("import") && l.includes("stepsPipeline"),
+      );
       // Only one import line should contain "pipeline"
       expect(pipelineImports.length).toBe(1);
     });
@@ -513,14 +515,14 @@ describe("generatePerformBlock", () => {
   it("generates pipeline block for static return", () => {
     const analysis = analyzeHandlerArrow("async () => ({ isSuccess: true, data: { ok: true } })");
     const block = generatePerformBlock(analysis, "", "  ");
-    expect(block).toContain("perform: pipeline(");
+    expect(block).toContain("perform: stepsPipeline(");
     expect(block).toContain("r.step.return((ctx) => ({ isSuccess: true, data: { ok: true } })");
   });
 
   it("generates pipeline block with schema type parameter", () => {
     const analysis = analyzeHandlerArrow("async () => ({ isSuccess: true, data: { ok: true } })");
     const block = generatePerformBlock(analysis, "typeof InvoiceSchema", "  ");
-    expect(block).toContain("pipeline<typeof InvoiceSchema, unknown>");
+    expect(block).toContain("stepsPipeline<typeof InvoiceSchema, unknown>");
   });
 
   it("returns null for non-convertible analysis", () => {

package/src/engine/__tests__/pipeline-engine.test.ts

@@ -1,4 +1,4 @@
-// Pipeline-engine unit tests — defineWriteHandler({ perform: pipeline(...) })
+// Pipeline-engine unit tests — defineWriteHandler({ perform: stepsPipeline(...) })
 // boundary, run-pipeline runner contract, defineStep registry guards.
 // Sub-step-builders (branch, forEach) live in pipeline-sub-pipelines.test.ts;
 // boot-validator in validate-projection-allowlist.test.ts.
@@ -9,7 +9,7 @@ import { z } from "zod";
 import { TestUsers } from "../../stack";
 import { defineWriteHandler } from "../define-handler";
 import { defineStep } from "../define-step";
-import { pipeline } from "../pipeline";
+import { stepsPipeline } from "../pipeline";
 import type { WriteEvent } from "../types/handlers";
 import { buildMinimalCtx } from "./_pipeline-test-utils";
 
@@ -19,7 +19,7 @@ describe("pipeline engine (return / compute / registry guards)", () => {
       name: "demo:noop",
       schema: z.object({ greeting: z.string() }),
       access: { roles: ["User"] },
-      perform: pipeline<{ greeting: string }, { echoed: string }>(({ event, r }) => [
+      perform: stepsPipeline<{ greeting: string }, { echoed: string }>(({ event, r }) => [
         r.step.return(() => ({
           isSuccess: true as const,
           data: { echoed: event.payload.greeting },
@@ -49,7 +49,7 @@ describe("pipeline engine (return / compute / registry guards)", () => {
       name: "demo:static",
       schema: z.object({}),
       access: { roles: ["User"] },
-      perform: pipeline<Record<string, never>, { ok: boolean }>(({ r }) => [
+      perform: stepsPipeline<Record<string, never>, { ok: boolean }>(({ r }) => [
         r.step.return({ isSuccess: true as const, data: { ok: true } }),
       ]),
     });
@@ -89,7 +89,7 @@ describe("pipeline engine (return / compute / registry guards)", () => {
       name: "demo:no-return",
       schema: z.object({}),
       access: { roles: ["User"] },
-      perform: pipeline<Record<string, never>, never>(() => []),
+      perform: stepsPipeline<Record<string, never>, never>(() => []),
     });
 
     await expect(
@@ -105,7 +105,7 @@ describe("pipeline engine (return / compute / registry guards)", () => {
       name: "demo:thread",
       schema: z.object({ base: z.number() }),
       access: { roles: ["User"] },
-      perform: pipeline<{ base: number }, { sum: number }>(({ event, r }) => [
+      perform: stepsPipeline<{ base: number }, { sum: number }>(({ event, r }) => [
         r.step.compute("offset", () => 10),
         r.step.compute("doubledBase", () => event.payload.base * 2),
         r.step.return(({ steps }) => ({
@@ -133,7 +133,7 @@ describe("pipeline engine (return / compute / registry guards)", () => {
       name: "demo:fresh",
       schema: z.object({}),
       access: { roles: ["User"] },
-      perform: pipeline<Record<string, never>, { tick: number }>(({ r }) => [
+      perform: stepsPipeline<Record<string, never>, { tick: number }>(({ r }) => [
         r.step.compute("tick", () => ++counter),
         r.step.return(({ steps }) => ({
           isSuccess: true as const,
@@ -161,7 +161,7 @@ describe("pipeline engine (return / compute / registry guards)", () => {
       name: "demo:unknown-kind",
       schema: z.object({}),
       access: { roles: ["User"] },
-      perform: pipeline<Record<string, never>, never>(() => [
+      perform: stepsPipeline<Record<string, never>, never>(() => [
         // Hand-crafted instance with a kind that's never been registered —
         // simulates a typo in a future step-builder factory.
         { kind: "this-step-does-not-exist", args: {} },
@@ -190,7 +190,7 @@ describe("pipeline engine (return / compute / registry guards)", () => {
       schema: z.object({}),
       access: { roles: ["User"] },
       handler: async () => ({ isSuccess: true as const, data: {} }),
-      perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+      perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
         r.step.return({ isSuccess: true as const, data: { ok: true } }),
       ]),
     } as unknown as Parameters<typeof defineWriteHandler>[0];

package/src/engine/__tests__/pipeline-handler.integration.test.ts

@@ -60,7 +60,7 @@ import {
 import { defineFeature } from "../define-feature";
 import { defineWriteHandler } from "../define-handler";
 import { createEntity, createTextField } from "../factories";
-import { pipeline } from "../pipeline";
+import { stepsPipeline } from "../pipeline";
 
 const echoSchema = z.object({ greeting: z.string() });
 
@@ -70,7 +70,7 @@ const echoHandler = defineWriteHandler({
   name: "echo",
   schema: echoSchema,
   access: { roles: ["Admin"] },
-  perform: pipeline<z.infer<typeof echoSchema>, { echoed: string; from: string }>(
+  perform: stepsPipeline<z.infer<typeof echoSchema>, { echoed: string; from: string }>(
     ({ event, r }) => [
       r.step.return(() => ({
         isSuccess: true as const,
@@ -90,7 +90,7 @@ const explodeHandler = defineWriteHandler({
   name: "explode",
   schema: explodeSchema,
   access: { roles: ["Admin"] },
-  perform: pipeline<z.infer<typeof explodeSchema>, never>(({ r }) => [
+  perform: stepsPipeline<z.infer<typeof explodeSchema>, never>(({ r }) => [
     r.step.return(() => {
       throw new Error("boom");
     }),
@@ -106,7 +106,7 @@ const compoundHandler = defineWriteHandler({
   name: "compound",
   schema: compoundSchema,
   access: { roles: ["Admin"] },
-  perform: pipeline<z.infer<typeof compoundSchema>, { sum: number; userId: string }>(
+  perform: stepsPipeline<z.infer<typeof compoundSchema>, { sum: number; userId: string }>(
     ({ event, r }) => [
       r.step.compute("offset", () => 100),
       r.step.compute("doubledBase", () => event.payload.base * 2),
@@ -147,7 +147,7 @@ const logHandler = defineWriteHandler({
   schema: logSchema,
   access: { roles: ["Admin"] },
   // Outer-`event`-capture pattern — see compoundHandler above for the why.
-  perform: pipeline<z.infer<typeof logSchema>, { correlationId: string }>(({ event, r }) => [
+  perform: stepsPipeline<z.infer<typeof logSchema>, { correlationId: string }>(({ event, r }) => [
     r.step.unsafeProjectionUpsert({
       table: pipelineDemoLogTable,
       on: ["correlationId"],
@@ -182,7 +182,7 @@ const widgetCreateHandler = defineWriteHandler({
   name: "widget:create",
   schema: widgetSchema,
   access: { roles: ["Admin"] },
-  perform: pipeline<z.infer<typeof widgetSchema>, { id: string }>(({ event, r }) => [
+  perform: stepsPipeline<z.infer<typeof widgetSchema>, { id: string }>(({ event, r }) => [
     r.step.aggregate.create("widget", {
       executor: widgetExecutor,
       data: () => ({ label: event.payload.label }),
@@ -202,7 +202,7 @@ const annotateHandler = defineWriteHandler({
   name: "widget:annotate",
   schema: annotateSchema,
   access: { roles: ["Admin"] },
-  perform: pipeline<z.infer<typeof annotateSchema>, { id: string }>(({ event, r }) => [
+  perform: stepsPipeline<z.infer<typeof annotateSchema>, { id: string }>(({ event, r }) => [
     r.step.aggregate.create("widget", {
       executor: widgetExecutor,
       data: () => ({ label: event.payload.label }),
@@ -230,7 +230,7 @@ const widgetUpdateHandler = defineWriteHandler({
   name: "widget:update",
   schema: widgetUpdateSchema,
   access: { roles: ["Admin"] },
-  perform: pipeline<z.infer<typeof widgetUpdateSchema>, { id: string }>(({ event, r }) => [
+  perform: stepsPipeline<z.infer<typeof widgetUpdateSchema>, { id: string }>(({ event, r }) => [
     r.step.aggregate.update("widget", {
       executor: widgetExecutor,
       id: () => event.payload.id,
@@ -254,7 +254,7 @@ const widgetBrokenHandler = defineWriteHandler({
   name: "widget:create-broken",
   schema: z.object({}),
   access: { roles: ["Admin"] },
-  perform: pipeline<Record<string, never>, { id: string }>(({ r }) => [
+  perform: stepsPipeline<Record<string, never>, { id: string }>(({ r }) => [
     r.step.aggregate.create("widget", {
       executor: widgetExecutor,
       // Intentionally omits the `label` field that the entity declares
@@ -278,7 +278,7 @@ const widgetCreateThenThrowHandler = defineWriteHandler({
   name: "widget:create-then-throw",
   schema: z.object({ label: z.string() }),
   access: { roles: ["Admin"] },
-  perform: pipeline<{ label: string }, never>(({ event, r }) => [
+  perform: stepsPipeline<{ label: string }, never>(({ event, r }) => [
     r.step.aggregate.create("widget", {
       executor: widgetExecutor,
       data: () => ({ label: event.payload.label }),
@@ -303,7 +303,7 @@ const forEachThenThrowHandler = defineWriteHandler({
   name: "widget:foreach-then-throw",
   schema: forEachThenThrowSchema,
   access: { roles: ["Admin"] },
-  perform: pipeline<{ labels: string[] }, never>(({ event, r }) => [
+  perform: stepsPipeline<{ labels: string[] }, never>(({ event, r }) => [
     r.step.forEach({
       over: () => event.payload.labels,
       as: "label",
@@ -337,7 +337,7 @@ const lookupHandler = defineWriteHandler({
   name: "widget:lookup",
   schema: lookupSchema,
   access: { roles: ["Admin"] },
-  perform: pipeline<z.infer<typeof lookupSchema>, { found: boolean; label: string | null }>(
+  perform: stepsPipeline<z.infer<typeof lookupSchema>, { found: boolean; label: string | null }>(
     ({ event, r }) => [
       r.step.read.findOne("widget", {
         table: widgetTable,
@@ -358,7 +358,7 @@ const listAllHandler = defineWriteHandler({
   name: "widget:list",
   schema: z.object({}),
   access: { roles: ["Admin"] },
-  perform: pipeline<Record<string, never>, { count: number }>(({ r }) => [
+  perform: stepsPipeline<Record<string, never>, { count: number }>(({ r }) => [
     r.step.read.findMany("widgets", { table: widgetTable }),
     r.step.return(({ steps }) => ({
       isSuccess: true as const,
@@ -374,7 +374,7 @@ const listLimitedHandler = defineWriteHandler({
   name: "widget:list-one",
   schema: z.object({}),
   access: { roles: ["Admin"] },
-  perform: pipeline<Record<string, never>, { count: number }>(({ r }) => [
+  perform: stepsPipeline<Record<string, never>, { count: number }>(({ r }) => [
     r.step.read.findMany("widgets", { table: widgetTable, limit: 1 }),
     r.step.return(({ steps }) => ({
       isSuccess: true as const,
@@ -388,7 +388,7 @@ const purgeLogHandler = defineWriteHandler({
   name: "log:purge",
   schema: purgeLogSchema,
   access: { roles: ["Admin"] },
-  perform: pipeline<z.infer<typeof purgeLogSchema>, { ok: true }>(({ event, r }) => [
+  perform: stepsPipeline<z.infer<typeof purgeLogSchema>, { ok: true }>(({ event, r }) => [
     r.step.unsafeProjectionDelete({
       table: pipelineDemoLogTable,
       where: () => ({ correlationId: event.payload.correlationId }),
@@ -403,7 +403,7 @@ const conditionalLogHandler = defineWriteHandler({
   name: "log:conditional",
   schema: conditionalLogSchema,
   access: { roles: ["Admin"] },
-  perform: pipeline<z.infer<typeof conditionalLogSchema>, { ok: true }>(({ event, r }) => [
+  perform: stepsPipeline<z.infer<typeof conditionalLogSchema>, { ok: true }>(({ event, r }) => [
     r.step.branch({
       if: () => event.payload.message.length > 0,
       onTrue: [
@@ -428,7 +428,7 @@ const bulkLogHandler = defineWriteHandler({
   name: "log:bulk",
   schema: bulkLogSchema,
   access: { roles: ["Admin"] },
-  perform: pipeline<z.infer<typeof bulkLogSchema>, { count: number }>(({ event, r }) => [
+  perform: stepsPipeline<z.infer<typeof bulkLogSchema>, { count: number }>(({ event, r }) => [
     r.step.forEach({
       over: () => event.payload.correlationIds,
       as: "correlationId",
@@ -476,7 +476,7 @@ const demoPipelineFeature = defineFeature("demoPipeline", (r) => {
 let stack: TestStack;
 const admin = TestUsers.admin;
 
-describe("defineWriteHandler({ perform: pipeline(...) }) — real dispatcher path", () => {
+describe("defineWriteHandler({ perform: stepsPipeline(...) }) — real dispatcher path", () => {
   beforeAll(async () => {
     stack = await setupTestStack({ features: [demoPipelineFeature] });
     // Push the read-side-projection table — not registered as an entity,

package/src/engine/__tests__/pipeline-observability.integration.test.ts

@@ -20,7 +20,7 @@ import { createRecordingProvider, type RecordingProvider } from "../../testing";
 import { defineFeature } from "../define-feature";
 import { defineWriteHandler } from "../define-handler";
 import { createEntity, createTextField } from "../factories";
-import { pipeline } from "../pipeline";
+import { stepsPipeline } from "../pipeline";
 
 // Handler whose step bodies emit a span + a metric. The recording
 // provider afterwards lets us assert both landed.
@@ -30,7 +30,7 @@ const observedHandler = defineWriteHandler({
   name: "observed",
   schema: observedSchema,
   access: { roles: ["Admin"] },
-  perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+  perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
     r.step.compute("traced", (ctx) => {
       // Span emitted from inside a step. End it explicitly because
       // step.run is sync-or-async-but-not-otel-instrumented; the

package/src/engine/__tests__/pipeline-performance.integration.test.ts

@@ -1,6 +1,6 @@
 // Pipeline-engine performance smoke-test.
 //
-// Compares the M.1 pipeline-form handler ({ perform: pipeline(...) })
+// Compares the M.1 pipeline-form handler ({ perform: stepsPipeline(...) })
 // against the equivalent free-form handler ({ handler: async (...) })
 // over N identical writes against the real Postgres stack. The point
 // is NOT to optimise — the pipeline-form is a thin wrapper, not a
@@ -28,7 +28,7 @@ import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } fr
 import { defineFeature } from "../define-feature";
 import { defineWriteHandler } from "../define-handler";
 import { createEntity, createNumberField, createTextField } from "../factories";
-import { pipeline } from "../pipeline";
+import { stepsPipeline } from "../pipeline";
 
 // Same logical operation in both handler-forms: read input, return a
 // trivial transformed payload. No DB-write — the goal is to compare
@@ -41,7 +41,7 @@ const trivialPipeline = defineWriteHandler({
   name: "trivial:pipeline",
   schema: trivialSchema,
   access: { roles: ["Admin"] },
-  perform: pipeline<{ n: number }, { doubled: number }>(({ event, r }) => [
+  perform: stepsPipeline<{ n: number }, { doubled: number }>(({ event, r }) => [
     r.step.return(() => ({
       isSuccess: true as const,
       data: { doubled: event.payload.n * 2 },

package/src/engine/__tests__/pipeline-sub-pipelines.test.ts

@@ -9,7 +9,7 @@ import { describe, expect, it } from "bun:test";
 import { z } from "zod";
 import { TestUsers } from "../../stack";
 import { defineWriteHandler } from "../define-handler";
-import { pipeline } from "../pipeline";
+import { stepsPipeline } from "../pipeline";
 import { buildBranchStep } from "../steps/branch";
 import { buildForEachStep } from "../steps/for-each";
 import { buildReturnStep } from "../steps/return";
@@ -21,7 +21,7 @@ describe("r.step.branch", () => {
       name: "demo:branch-then",
       schema: z.object({}),
       access: { roles: ["User"] },
-      perform: pipeline<Record<string, never>, { value: number }>(({ r }) => [
+      perform: stepsPipeline<Record<string, never>, { value: number }>(({ r }) => [
         r.step.branch({
           if: () => true,
           onTrue: [r.step.compute("inThen", () => 42)],
@@ -47,7 +47,7 @@ describe("r.step.branch", () => {
       name: "demo:branch-else",
       schema: z.object({}),
       access: { roles: ["User"] },
-      perform: pipeline<Record<string, never>, { value: number }>(({ r }) => [
+      perform: stepsPipeline<Record<string, never>, { value: number }>(({ r }) => [
         r.step.branch({
           if: () => false,
           onTrue: [r.step.compute("inThen", () => 42)],
@@ -72,7 +72,7 @@ describe("r.step.branch", () => {
       name: "demo:branch-noop",
       schema: z.object({}),
       access: { roles: ["User"] },
-      perform: pipeline<Record<string, never>, { ran: boolean }>(({ r }) => [
+      perform: stepsPipeline<Record<string, never>, { ran: boolean }>(({ r }) => [
         r.step.branch({
           if: () => false,
           onTrue: [r.step.compute("ran", () => true)],
@@ -122,7 +122,7 @@ describe("r.step.forEach", () => {
       name: "demo:foreach",
       schema: z.object({}),
       access: { roles: ["User"] },
-      perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+      perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
         r.step.forEach({
           over: () => [10, 20, 30],
           as: "n",
@@ -153,7 +153,7 @@ describe("r.step.forEach", () => {
       name: "demo:foreach-cleanup",
       schema: z.object({}),
       access: { roles: ["User"] },
-      perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+      perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
         r.step.forEach({
           over: () => [1],
           as: "tmp",
@@ -180,7 +180,7 @@ describe("r.step.forEach", () => {
       name: "demo:foreach-empty",
       schema: z.object({}),
       access: { roles: ["User"] },
-      perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+      perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
         r.step.forEach({
           over: () => [],
           as: "n",
@@ -233,7 +233,7 @@ describe("r.step.forEach", () => {
       name: "demo:foreach-throws",
       schema: z.object({}),
       access: { roles: ["User"] },
-      perform: pipeline<Record<string, never>, never>(({ r }) => [
+      perform: stepsPipeline<Record<string, never>, never>(({ r }) => [
         r.step.forEach({
           over: () => [1, 2, 3],
           as: "item",
@@ -266,7 +266,7 @@ describe("r.step.forEach", () => {
       name: "demo:foreach-bad-over",
       schema: z.object({}),
       access: { roles: ["User"] },
-      perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+      perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
         r.step.forEach({
           // Cast: TypeScript would normally catch this; the test exercises
           // the runtime guard for hand-crafted / dynamically built cases.

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

@@ -11,7 +11,7 @@ import { defineFeature } from "../define-feature";
 import { defineWriteHandler } from "../define-handler";
 import { defineStep } from "../define-step";
 import { createEntity, createTextField } from "../factories";
-import { pipeline } from "../pipeline";
+import { stepsPipeline } from "../pipeline";
 import { validateProjectionAllowlist } from "../validate-projection-allowlist";
 
 describe("validateProjectionAllowlist", () => {
@@ -28,7 +28,7 @@ describe("validateProjectionAllowlist", () => {
           name: "log",
           schema: z.object({ msg: z.string() }),
           access: { roles: ["User"] },
-          perform: pipeline<{ msg: string }, { ok: true }>(({ event, r }) => [
+          perform: stepsPipeline<{ msg: string }, { ok: true }>(({ event, r }) => [
             r.step.unsafeProjectionUpsert({
               table: demoLogTable,
               on: ["id"],
@@ -70,7 +70,7 @@ describe("validateProjectionAllowlist", () => {
           name: "sneaky",
           schema: z.object({}),
           access: { roles: ["User"] },
-          perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+          perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
             r.step.unsafeProjectionUpsert({
               table: widgetsTable,
               on: ["id"],
@@ -113,7 +113,7 @@ describe("validateProjectionAllowlist", () => {
           name: "sneaky-delete",
           schema: z.object({}),
           access: { roles: ["User"] },
-          perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+          perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
             r.step.unsafeProjectionDelete({
               table: widgetsTable,
               where: () => ({ id: "anything" }),
@@ -136,7 +136,7 @@ describe("validateProjectionAllowlist", () => {
           name: "purge",
           schema: z.object({}),
           access: { roles: ["User"] },
-          perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+          perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
             r.step.unsafeProjectionDelete({
               table: demoLogTable,
               where: () => ({ id: "anything" }),
@@ -162,7 +162,7 @@ describe("validateProjectionAllowlist", () => {
           name: "branchedWrite",
           schema: z.object({}),
           access: { roles: ["User"] },
-          perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+          perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
             r.step.branch({
               if: () => true,
               onTrue: [
@@ -195,7 +195,7 @@ describe("validateProjectionAllowlist", () => {
           name: "nestedWrite",
           schema: z.object({}),
           access: { roles: ["User"] },
-          perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+          perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
             r.step.forEach({
               over: () => [],
               as: "item",
@@ -230,7 +230,7 @@ describe("validateProjectionAllowlist", () => {
           name: "loopedWrite",
           schema: z.object({}),
           access: { roles: ["User"] },
-          perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+          perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
             r.step.forEach({
               over: () => [],
               as: "x",
@@ -267,7 +267,7 @@ describe("validateProjectionAllowlist", () => {
           name: "futureBuilder",
           schema: z.object({}),
           access: { roles: ["User"] },
-          perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+          perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
             // Hand-crafted StepInstance simulating a future builder
             // whose kind isn't registered via defineStep yet.
             {
@@ -316,7 +316,7 @@ describe("validateProjectionAllowlist", () => {
           name: "futureBuilder",
           schema: z.object({}),
           access: { roles: ["User"] },
-          perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+          perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
             {
               kind: futureKind,
               args: {
@@ -380,7 +380,7 @@ describe("validateProjectionAllowlist", () => {
           name: "sneak",
           schema: z.object({}),
           access: { roles: ["Admin"] },
-          perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+          perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
             r.step.webhook.send({
               url: "https://hooks.example/sneak",
               mode: "deferred",
@@ -404,7 +404,7 @@ describe("validateProjectionAllowlist", () => {
           name: "sneak",
           schema: z.object({}),
           access: { roles: ["Admin"] },
-          perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+          perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
             r.step.mail.send({
               to: "x@y.com",
               subject: "hi",
@@ -428,7 +428,7 @@ describe("validateProjectionAllowlist", () => {
           name: "sneak",
           schema: z.object({}),
           access: { roles: ["Admin"] },
-          perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+          perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
             r.step.callFeature("subResult", {
               handler: "other:write:do",
               payload: () => ({}),
@@ -451,7 +451,7 @@ describe("validateProjectionAllowlist", () => {
           name: "ok",
           schema: z.object({}),
           access: { roles: ["Admin"] },
-          perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+          perform: stepsPipeline<Record<string, never>, { ok: true }>(({ r }) => [
             r.step.webhook.send({
               url: "https://hooks.example/ok",
               mode: "deferred",
@@ -473,7 +473,7 @@ describe("validateProjectionAllowlist", () => {
           name: "log",
           schema: z.object({ msg: z.string() }),
           access: { roles: ["User"] },
-          perform: pipeline<{ msg: string }, { ok: true }>(({ event, r }) => [
+          perform: stepsPipeline<{ msg: string }, { ok: true }>(({ event, r }) => [
             r.step.unsafeProjectionUpsert({
               table: demoLogTable,
               on: ["id"],

package/src/engine/codemod/pipeline-codemod.ts

@@ -370,7 +370,7 @@ export function generatePerformBlock(
   const pipelineType = schemaType ? `<${schemaType}, unknown>` : "";
 
   return [
-    `perform: pipeline${pipelineType}(({ event, r }) => [`,
+    `perform: stepsPipeline${pipelineType}(({ event, r }) => [`,
     stepsStr,
     `  ${stepIndent}]),`,
   ].join("\n");
@@ -513,7 +513,7 @@ function contentHasPipelineImport(content: string): boolean {
   const importLine = content
     .split("\n")
     .find((l) => l.includes("import") && l.includes("@cosmicdrift/kumiko-framework/engine"));
-  return !!importLine && importLine.includes("pipeline");
+  return !!importLine && importLine.includes("stepsPipeline");
 }
 
 function ensurePipelineImport(content: string): string | null {
@@ -525,7 +525,7 @@ function ensurePipelineImport(content: string): string | null {
   const match = content.match(importRegex);
   if (match) {
     const existingImports = (match[1] as string).trim();
-    const newImports = existingImports ? `${existingImports}, pipeline` : "pipeline";
+    const newImports = existingImports ? `${existingImports}, stepsPipeline` : "stepsPipeline";
     return content.replace(
       importRegex,
       `import { ${newImports} } from "@cosmicdrift/kumiko-framework/engine"`,
@@ -611,7 +611,7 @@ export async function convertFile(
       if (importResult) {
         content = importResult;
       } else if (options.verbose) {
-        console.log(`  ~ ${filePath}: pipeline import not needed or already present`);
+        console.log(`  ~ ${filePath}: stepsPipeline import not needed or already present`);
       }
     }
 
@@ -621,7 +621,7 @@ export async function convertFile(
 
     const status = hadChanges ? "converted" : "skipped";
     const reason = hadChanges
-      ? "handler replaced with perform: pipeline(...)"
+      ? "handler replaced with perform: stepsPipeline(...)"
       : "no convertible handler";
     return { filePath, status, reason };
   } catch (err) {

package/src/engine/define-handler.ts

@@ -23,7 +23,7 @@ import type { PipelineDef } from "./types/step";
 // visible) and collapse `keyof TMap` to `never`. See the spike-findings
 // memory for the empirical proof.
 //
-// Two authoring forms — `handler` (free-form) or `perform: pipeline(...)`
+// Two authoring forms — `handler` (free-form) or `perform: stepsPipeline(...)`
 // (step-pipeline). A `perform` is compiled to a handler-function at
 // definition time; the dispatcher only ever sees `handler`.
 
@@ -126,7 +126,7 @@ export function defineWriteHandler<
     throw new Error(
       `defineWriteHandler("${def.name}"): both \`handler\` and \`perform\` are set. ` +
         `Pick one — \`handler\` for the free-form async function, ` +
-        `\`perform: pipeline(...)\` for the step-pipeline form. ` +
+        `\`perform: stepsPipeline(...)\` for the step-pipeline form. ` +
         `(See step-vocabulary.md for which form fits.)`,
     );
   }

package/src/engine/define-workflow.ts

@@ -57,7 +57,7 @@ export type WorkflowInput<TPayload = unknown, TData = unknown> = {
  * defineWorkflow({
  *   name: "user-onboarding",
  *   trigger: { kind: "event", eventType: "user.signed-up" },
- *   steps: pipeline(({ event, r }) => [
+ *   steps: stepsPipeline(({ event, r }) => [
  *     r.step.mail.send({ to: () => event.payload.email, subject: "Welcome!", body: "..." }),
  *     r.step.wait({ for: "P1D" }),
  *     r.step.read.findOne("user", { table: userTable, where: ... }),

package/src/engine/index.ts

@@ -179,18 +179,20 @@ export {
   filterReadFields,
 } from "./field-access";
 // findForbiddenMembershipRole/isForbiddenMembershipRole/
-// stripForbiddenMembershipRoles are Public API for host apps that build
-// their own membership handlers. FORBIDDEN_MEMBERSHIP_ROLES itself stays
-// internal (637/3) — exporting the raw Set would make its representation a
-// semver promise; the predicate functions are the intended surface.
+// stripForbiddenMembershipRoles/buildSessionRoles are Public API for host
+// apps that build their own membership handlers. FORBIDDEN_MEMBERSHIP_ROLES
+// itself stays internal (637/3) — exporting the raw Set would make its
+// representation a semver promise; the predicate functions are the intended
+// surface.
 export {
+  buildSessionRoles,
   findForbiddenMembershipRole,
   isForbiddenMembershipRole,
   stripForbiddenMembershipRoles,
 } from "./membership-roles";
 export type { OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule } from "./ownership";
 export { from } from "./ownership";
-export { buildPipelineSteps, pipeline } from "./pipeline";
+export { buildPipelineSteps, stepsPipeline } from "./pipeline";
 export { defineApply, defineMspApply, setFields } from "./projection-helpers";
 export type { BuiltinQnType, ParsedQn, QnType } from "./qualified-name";
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name";

package/src/engine/membership-roles.ts

@@ -30,3 +30,16 @@ export function findForbiddenMembershipRole(roles: readonly string[]): string |
 export function stripForbiddenMembershipRoles(roles: readonly string[]): readonly string[] {
   return roles.filter((role) => !isForbiddenMembershipRole(role));
 }
+
+// Single mint path for session roles: merges globalRoles with the stripped
+// membership portion and dedupes. Every place that builds a session's roles
+// from a membership should go through this instead of repeating
+// `new Set([...globalRoles, ...stripForbiddenMembershipRoles(x)])` — a new
+// mint site that forgets the strip is exactly the bug class this guards
+// against.
+export function buildSessionRoles(
+  globalRoles: readonly string[],
+  membershipRoles: readonly string[],
+): readonly string[] {
+  return Array.from(new Set([...globalRoles, ...stripForbiddenMembershipRoles(membershipRoles)]));
+}

package/src/engine/pipeline.ts

@@ -1,4 +1,4 @@
-// pipeline() — public factory used in defineWriteHandler({ perform: pipeline(...) }).
+// stepsPipeline() — public factory used in defineWriteHandler({ perform: stepsPipeline(...) }).
 //
 // The closure receives { event, r } and returns the immutable list of
 // step instances. `r` is the StepBuilder singleton; new tier-1 steps
@@ -8,15 +8,10 @@
 // the resolver-side PipelineCtx (run-pipeline.ts). Resolvers that need
 // prior step results destructure them from the resolver's ctx.
 //
-// Naming note (Followup #1): the public `pipeline()` helper shares its
-// name with the internal `packages/framework/src/pipeline/` directory
-// (dispatcher, lifecycle, outbox-poller). No user-visible collision —
-// the internal directory isn't an export — but maintainer repo-wide
-// grep for `pipeline` returns mixed results. If a rename ever lands,
-// candidates are `r.steps([...])` for the public API or
-// `engine-pipeline/` / `runtime/` for the internal directory.
-// Decision-cost grows with each new caller; the rename window narrows
-// after the first external consumer.
+// Renamed from `pipeline()` (Followup #1) — it shared its name with the
+// internal `packages/framework/src/pipeline/` directory (dispatcher,
+// lifecycle, outbox-poller), which made repo-wide grep for `pipeline`
+// return mixed results.
 
 import { buildAggregateAppendEventStep } from "./steps/aggregate-append-event";
 import { buildAggregateCreateStep } from "./steps/aggregate-create";
@@ -69,7 +64,7 @@ const stepBuilder: StepBuilder = {
   },
 };
 
-export function pipeline<TPayload = unknown, TData = unknown>(
+export function stepsPipeline<TPayload = unknown, TData = unknown>(
   closure: (ctx: PipelineBuildCtx<TPayload>) => readonly StepInstance[],
 ): PipelineDef<TPayload, TData> {
   return {

package/src/engine/run-pipeline.ts

@@ -64,7 +64,7 @@ export async function runPipeline<TPayload, TData, TMap extends object = KumikoE
   if (outcome.kind === "return") {
     // RETURN_RESULT_KEY is only produced by r.step.return, whose run()
     // returns WriteResult<unknown>. The pipeline's generic TData is
-    // bound at build time (defineWriteHandler ↔ pipeline<P, D>(...));
+    // bound at build time (defineWriteHandler ↔ stepsPipeline<P, D>(...));
     // matching the runtime value to that compile-time type is the
     // contract user-side. Cast crosses that boundary.
     return outcome.result as WriteResult<TData>;

package/src/engine/types/handlers.ts

@@ -796,7 +796,7 @@ export type WriteHandlerDef = {
   readonly access?: AccessRule;
   readonly unsafeSkipTransitionGuard?: boolean;
   readonly rateLimit?: RateLimitOption;
-  // Set when the author wrote a `perform: pipeline(...)` block. Boot-
+  // Set when the author wrote a `perform: stepsPipeline(...)` block. Boot-
   // validators (projection-allowlist) and Designer/AI tooling read this
   // to inspect the step list. Absent on free-form handlers.
   // Inline-import is intentional: step.ts imports HandlerContext from

package/src/engine/types/step.ts

@@ -126,7 +126,7 @@ export type StepInstance = {
 };
 
 /**
- * What `pipeline(closure)` returns. Carries the closure (instead of an
+ * What `stepsPipeline(closure)` returns. Carries the closure (instead of an
  * eagerly-built array) so each handler-call sees a fresh event ref and
  * the `r` step-builder is resolved at runtime, not at module-load time.
  *
@@ -140,7 +140,7 @@ export type StepInstance = {
  * `noUnusedVariables` marker, not user-facing). _TData is NOT inferred
  * from the closure body (r.step.return has its own per-call TData), so
  * callers must spell it explicitly:
- *   `pipeline<{ greeting: string }, { echoed: string }>(...)`
+ *   `stepsPipeline<{ greeting: string }, { echoed: string }>(...)`
  * Better DX is a known follow-up — see step-vocabulary.md M.1-Followups.
  */
 export type PipelineDef<TPayload = unknown, _TData = unknown> = {
@@ -149,7 +149,7 @@ export type PipelineDef<TPayload = unknown, _TData = unknown> = {
 };
 
 /**
- * Argument bundle passed to the closure inside `pipeline(closure)`.
+ * Argument bundle passed to the closure inside `stepsPipeline(closure)`.
  * Build-time only — no `steps`, no `scope`, no `db`: at build time no
  * step has run yet.
  *
@@ -314,7 +314,7 @@ export type StepNamespace = {
     },
   ) => StepInstance;
   // --- Tier-3 / Workflow-only steps ---
-  // Only available inside defineWorkflow ({ steps: pipeline(...) }).
+  // Only available inside defineWorkflow ({ steps: stepsPipeline(...) }).
   // Runtime guard: throws when used inside sync defineWriteHandler.
   readonly wait: (args: { readonly for: StepResolver<string> }) => StepInstance;
   readonly waitForEvent: (args: {

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

@@ -13,7 +13,7 @@
 // don't run at build time, so dummy event-payloads are fine.
 //
 // CLOSURE-BODY CONTRACT: the pipeline-closure body (the function passed
-// to `pipeline(...)`) must produce its step-list deterministically based
+// to `stepsPipeline(...)`) must produce its step-list deterministically based
 // on the step-builder `r` alone. Reading `event.payload` outside of
 // resolvers (i.e. at the top of the closure, not inside a step's `row:`
 // or `data:` callback) is forbidden — at boot the dummy payload is `{}`