@cosmicdrift/kumiko-bundled-features 0.235.3 → 0.236.0

package/src/feature-toggles/__tests__/feature-toggles.integration.test.ts

@@ -1,4 +1,4 @@
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   buildEntityTable,
@@ -18,21 +18,22 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
-import { createEventDispatcher, type EventConsumer } from "@cosmicdrift/kumiko-framework/pipeline";
 import {
+  createTestRedis,
   createTestUser,
   setupTestStack,
+  type TestRedis,
   type TestStack,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { createLateBoundHolder, seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import { createLateBoundHolder, seedRow, waitFor } from "@cosmicdrift/kumiko-framework/testing";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
-import { FEATURE_TOGGLE_SET_EVENT_NAME } from "../constants";
 import { createFeatureTogglesFeature } from "../feature";
 import { globalFeatureStateTable } from "../global-feature-state-table";
 import { GlobalFeatureToggleRuntime } from "../toggle-runtime";
+import { createRedisToggleSyncSignal, type RedisToggleSyncSignal } from "../toggle-sync-signal";
 
 // Widget — the "tenant" under test. toggleable(default=true), owns a
 // simple entity and a create-handler that writes via the event-store
@@ -595,98 +596,70 @@ describe("feature-toggles queries + audit automation", () => {
 
 // --- Multi-instance cache-sync (toggle-cache-sync MSP) ---
 //
-// Production scenario: two API instances share a DB. Instance A runs the
-// set-handler (flips widget off), Instance B didn't. Before this MSP,
-// B's runtime stayed stuck on the pre-flip snapshot until it was
-// restarted. Now B's dispatcher picks up the toggle-set event from the
-// events table (via the per-instance consumer cursor) and converges its
-// own snapshot.
-//
-// We simulate B with a hand-rolled second dispatcher against the same DB
-// — same pattern as the Welle-2.7 multi-instance tests in
-// event-dispatcher-multi-instance.integration.ts. Building a second
-// setupTestStack would need a shared DB pool across stacks, which adds
-// more test-infra than the scenario is worth; the hand-rolled consumer
-// mirrors exactly what the feature-toggles feature registers on the
-// primary stack.
+// Production scenario: two API instances share a DB + Redis. Instance A
+// runs the set-handler (flips widget off); its toggle-cache-sync MSP wins
+// the shared cursor and calls runtime.broadcastToggle, which publishes on
+// its syncSignal. Instance B's own GlobalFeatureToggleRuntime, subscribed
+// to the same Redis channel, applies the flip without ever running the
+// MSP itself — delivery is "shared", so only ONE process's dispatcher
+// processes a given toggle-set event; the signal is what makes every
+// OTHER already-running process learn about it. This is "der Kern" this
+// PR adds: without a real transport under broadcastToggle, only the
+// cursor-winning process would ever converge.
 describe("multi-instance cache-sync via toggle-cache-sync MSP", () => {
-  test("flip on instance A propagates to instance B after its dispatcher ticks", async () => {
-    // Instance B's runtime — same DB as instance A's `runtime`, but its
-    // own in-memory snapshot. `initialize()` loads the pre-existing rows;
-    // at this point there are no override rows (beforeEach wiped the
-    // table), so `widget` is on via its toggleable default.
-    const runtimeB = new GlobalFeatureToggleRuntime(stack.db, stack.registry);
-    await runtimeB.initialize();
-    expect(runtimeB.effectiveFeatures().has("widget")).toBe(true);
+  let testRedis: TestRedis;
+  let signalA: RedisToggleSyncSignal | undefined;
+  let signalB: RedisToggleSyncSignal | undefined;
 
-    // Instance B's dispatcher — same consumer name as the feature's MSP
-    // so per-instance cursor rows stay aligned with production reality
-    // (each instance owns one cursor row keyed by (name, instance_id)).
-    // The handler mirrors the MSP's apply: narrow the payload, call
-    // runtime.apply. In production this code lives in the
-    // r.multiStreamProjection declaration; here we hand-roll it to keep
-    // the second runtime a local object.
-    const consumer: EventConsumer = {
-      name: "feature-toggles:projection:toggle-cache-sync",
-      delivery: "per-instance",
-      handler: async (event) => {
-        if (event.type !== FEATURE_TOGGLE_SET_EVENT_NAME) return;
-        const payload = event.payload as { featureName: string; enabled: boolean };
-        runtimeB.apply(payload.featureName, payload.enabled);
-      },
-    };
-    const dispatcherB = createEventDispatcher({
-      db: stack.db,
-      consumers: [consumer],
-      context: { db: stack.db, registry: stack.registry },
-      instanceId: "test-instance-B",
-      batchSize: 200,
-      pollIntervalMs: 5000,
-    });
-    await dispatcherB.ensureRegistered();
+  beforeAll(async () => {
+    testRedis = await createTestRedis();
+  });
 
-    // Flip widget off on "instance A" via the HTTP path. This triggers:
-    //   1. DB row write (globalFeatureStateTable)
-    //   2. ctx.appendEvent (toggle-set into events-table)
-    //   3. runtime.apply on A's in-memory snapshot (fast-path)
-    await stack.http.write(
-      "feature-toggles:write:set",
-      { featureName: "widget", enabled: false },
-      admin,
-    );
+  afterAll(async () => {
+    await testRedis.cleanup();
+  });
 
-    // A sees the flip immediately (local apply in set-handler).
-    expect(runtime.effectiveFeatures().has("widget")).toBe(false);
+  afterEach(async () => {
+    await Promise.all([signalA?.close(), signalB?.close()]);
+    signalA = undefined;
+    signalB = undefined;
+  });
 
-    // B hasn't ticked yet — its snapshot still says widget is on.
-    // This is the exact stale-cache bug this MSP is solving.
+  test("flip via instance A's runtime converges instance B's runtime over Redis", async () => {
+    signalA = createRedisToggleSyncSignal(testRedis.redisUrl);
+    signalB = createRedisToggleSyncSignal(testRedis.redisUrl);
+    const runtimeA = new GlobalFeatureToggleRuntime(stack.db, stack.registry, signalA);
+    const runtimeB = new GlobalFeatureToggleRuntime(stack.db, stack.registry, signalB);
+    await runtimeA.initialize();
+    await runtimeB.initialize();
+    expect(runtimeA.effectiveFeatures().has("widget")).toBe(true);
     expect(runtimeB.effectiveFeatures().has("widget")).toBe(true);
 
-    // B's dispatcher ticks: consumes the toggle-set event, apply fires,
-    // runtimeB converges.
-    await dispatcherB.runOnce();
+    // Retry the broadcast inside the predicate — same psubscribe-ack race
+    // as the SSE broker's Redis tests (a signal's subscription may not
+    // have landed the instant it's constructed).
+    await waitFor(() => {
+      runtimeA.broadcastToggle("widget", false);
+      return !runtimeB.effectiveFeatures().has("widget");
+    });
     expect(runtimeB.effectiveFeatures().has("widget")).toBe(false);
 
     // Flip back on — regression-check: propagation works both ways, not
     // just a one-shot on the first event.
-    await stack.http.write(
-      "feature-toggles:write:set",
-      { featureName: "widget", enabled: true },
-      admin,
-    );
-    expect(runtime.effectiveFeatures().has("widget")).toBe(true);
-    expect(runtimeB.effectiveFeatures().has("widget")).toBe(false);
-    await dispatcherB.runOnce();
+    await waitFor(() => {
+      runtimeA.broadcastToggle("widget", true);
+      return runtimeB.effectiveFeatures().has("widget");
+    });
     expect(runtimeB.effectiveFeatures().has("widget")).toBe(true);
   });
 
-  test("per-instance delivery: the primary stack's dispatcher also fires the MSP (double-apply is idempotent)", async () => {
-    // The feature registers the MSP with delivery="per-instance", so the
-    // primary stack's dispatcher also owns a cursor row and fires the
-    // handler on every toggle-set event — even on the instance that just
-    // wrote locally via the set-handler. `runtime.apply` is Map.set, so
-    // the second write is a no-op. We verify the dispatcher-tick path
-    // doesn't corrupt state.
+  test("shared delivery: the primary stack's own dispatcher tick re-applies idempotently", async () => {
+    // The feature registers the MSP with delivery="shared" — a single
+    // process (here, the primary test stack, which has no syncSignal
+    // configured) can win its own cursor and re-apply a value it already
+    // set locally via the set-handler. `runtime.apply` is Map.set, so the
+    // second write is a no-op. We verify the dispatcher-tick path doesn't
+    // corrupt state.
     await stack.http.write(
       "feature-toggles:write:set",
       { featureName: "widget", enabled: false },

package/src/feature-toggles/feature.ts

@@ -45,7 +45,7 @@ export function createFeatureTogglesFeature(
 ): FeatureDefinition {
   return defineFeature("feature-toggles", (r) => {
     r.describe(
-      'Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: "per-instance"` syncs the snapshot across instances whenever a `toggle-set` event is appended.',
+      'Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: "shared"` syncs the snapshot across instances whenever a `toggle-set` event is appended.',
     );
     r.uiHints({
       displayLabel: "Feature Toggles · Operator Switches",
@@ -103,24 +103,30 @@ export function createFeatureTogglesFeature(
 
     r.translations({ keys: FEATURE_TOGGLES_I18N });
 
-    // toggle-cache-sync — multi-instance snapshot propagation. Every
-    // API/worker instance runs its own dispatcher cursor on this MSP
-    // (delivery: "per-instance") and converges its in-memory snapshot on
-    // every toggle-set event it observes. Named "cache-sync" (not
-    // "projection" or "audit") because it's side-effect-only
-    // infrastructure — the framework's boot-validator also rejects
-    // per-instance MSPs that carry a `table`.
+    // toggle-cache-sync — multi-instance snapshot propagation. One shared
+    // cursor reads every toggle-set event once (fw#2625); the winning
+    // process's handler calls runtime.broadcastToggle, which publishes on
+    // GlobalFeatureToggleRuntime's syncSignal so every process (including
+    // the one that won the cursor) applies the flip to its own snapshot —
+    // see toggle-runtime.ts and toggle-sync-signal.ts. Without a syncSignal
+    // configured (no REDIS_URL — single-process dev/test), broadcastToggle
+    // applies directly; there is nobody else to reach. Named "cache-sync"
+    // (not "projection" or "audit") because it's side-effect-only
+    // infrastructure.
     //
     // Why this is correct alongside the set-handler's own `runtime.apply`:
     //   - local apply = immediate response-latency optimization so the
     //     next request on the same instance sees the flip without a
-    //     dispatcher-tick round-trip
+    //     dispatcher-tick + Pub/Sub round-trip
     //   - MSP = multi-instance propagation + crash-recovery. If a process
     //     crashes between appendEvent (persisted) and the local apply
-    //     (volatile), the MSP rebuilds the snapshot on restart; if
-    //     instance B never ran the write, the MSP is how it learns. Both
-    //     paths are idempotent — apply is Map.set, replay on boot just
-    //     converges to the DB state that initialize() already loaded.
+    //     (volatile), the MSP rebuilds the snapshot on restart via
+    //     initialize(); if another instance never ran the write, the MSP
+    //     + syncSignal is how it learns. All paths are idempotent — apply
+    //     is Map.set.
+    //
+    // startFrom: "now" — history is meaningless here, a flip is only ever
+    // relevant to processes already running when it happens.
     //
     // Requires: options.getRuntime() must resolve by the time the
     // dispatcher processes its first toggle-set event. The holder-based
@@ -128,7 +134,8 @@ export function createFeatureTogglesFeature(
     // this in setupTestStack and production boot.
     r.multiStreamProjection({
       name: "toggle-cache-sync",
-      delivery: "per-instance",
+      delivery: "shared",
+      startFrom: "now",
       apply: {
         [FEATURE_TOGGLE_SET_EVENT_NAME]: async (event) => {
           // The event payload shape is guaranteed by featureToggleSetSchema
@@ -142,7 +149,7 @@ export function createFeatureTogglesFeature(
                 "was wired up without `getRuntime`. Wire the accessor in your app-config.",
             );
           }
-          options.getRuntime().apply(payload.featureName, payload.enabled);
+          options.getRuntime().broadcastToggle(payload.featureName, payload.enabled);
         },
       },
     });
@@ -158,4 +165,6 @@ export { globalFeatureStateTable, globalFeatureStateTableMeta } from "./global-f
 export {
   createFeatureToggleRuntime,
   GlobalFeatureToggleRuntime,
+  type ToggleSyncSignal,
 } from "./toggle-runtime";
+export { createRedisToggleSyncSignal, type RedisToggleSyncSignal } from "./toggle-sync-signal";

package/src/feature-toggles/index.ts

@@ -8,10 +8,13 @@ export {
 export {
   createFeatureToggleRuntime,
   createFeatureTogglesFeature,
+  createRedisToggleSyncSignal,
   FEATURE_TOGGLE_SET_EVENT_NAME,
   FeatureToggleErrors,
   type FeatureTogglesOptions,
   GlobalFeatureToggleRuntime,
   globalFeatureStateTable,
   globalFeatureStateTableMeta,
+  type RedisToggleSyncSignal,
+  type ToggleSyncSignal,
 } from "./feature";

package/src/feature-toggles/toggle-runtime.ts

@@ -7,23 +7,43 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { globalFeatureStateTable } from "./global-feature-state-table";
 
+// Cross-replica transport for a toggle flip (fw#2625). Deliberately narrow
+// (featureName + enabled, not a generic channel/payload pair) so a caller
+// can't wire the wrong signal instance in by accident — see
+// createRedisToggleSyncSignal (toggle-sync-signal.ts) for the Redis-backed
+// implementation, built on the framework's generic PubSubSignal.
+export type ToggleSyncSignal = {
+  publish(featureName: string, enabled: boolean): void;
+  onMessage(listener: (featureName: string, enabled: boolean) => void): void;
+};
+
 // Holds the current global-override snapshot in memory and exposes a
 // synchronous reader — the dispatcher's feature-gate calls it on every
 // handler invocation, so this must not do I/O on the hot path. The
 // snapshot is loaded once at boot via `.initialize()`, refreshed by the
-// set-handler on the local instance, and kept in sync across
-// instances by the `toggle-cache-sync` MSP (declared on the
-// feature-toggles feature, delivery: "per-instance"). Every API/worker
-// process observes every toggle-set event and applies it to its local
-// snapshot — no Redis / SSE / polling needed; the existing events-table
-// + event-dispatcher pipeline handles propagation.
+// set-handler on the local instance, and kept in sync across instances by
+// the `toggle-cache-sync` MSP (declared on the feature-toggles feature,
+// delivery: "shared") calling `broadcastToggle()`. With a `syncSignal`
+// configured (Redis — the same REDIS_URL-gated assumption the SSE broker
+// makes), that fans out to every process; without one (single-process
+// dev/test), `broadcastToggle` applies directly, matching the old
+// per-instance behavior for the only process there is.
 export class GlobalFeatureToggleRuntime {
   private snapshot = new Map<string, boolean>();
 
   constructor(
     private readonly db: DbConnection,
     private readonly registry: Registry,
-  ) {}
+    private readonly syncSignal?: ToggleSyncSignal,
+  ) {
+    // Every process, including the one that calls broadcastToggle, learns
+    // of a flip through this same subscription — mirrors the SSE broker's
+    // publish-then-echo-to-self pattern instead of a separate local-apply
+    // path that could drift from the signal-delivered one.
+    this.syncSignal?.onMessage((featureName, enabled) => {
+      this.apply(featureName, enabled);
+    });
+  }
 
   async initialize(): Promise<void> {
     type Row = { featureName: string; enabled: boolean };
@@ -47,6 +67,23 @@ export class GlobalFeatureToggleRuntime {
     this.snapshot.set(featureName, enabled);
   }
 
+  // Called by the toggle-cache-sync MSP handler (feature.ts) — the one
+  // process whose shared cursor won a given toggle-set event. With a
+  // syncSignal configured, publishing (rather than applying directly) is
+  // what reaches every OTHER already-running process; this process learns
+  // of its own publish the same way, through the constructor's
+  // subscription. Without a syncSignal there is nobody else to reach, so
+  // apply directly — this is the "no REDIS_URL" / single-process path.
+  broadcastToggle(featureName: string, enabled: boolean): void {
+    if (this.syncSignal) {
+      this.syncSignal.publish(featureName, enabled);
+      // skip: apply() runs when the publish echoes back through this
+      // process's own subscription, not here — see the comment above.
+      return;
+    }
+    this.apply(featureName, enabled);
+  }
+
   // Raw per-feature override, bypassing the requires() cascade —
   // `undefined` means "no explicit row, inherits toggleableDefault"
   // (distinct from an explicit `false`). Used by composeTierResolver to
@@ -77,8 +114,9 @@ export class GlobalFeatureToggleRuntime {
 export async function createFeatureToggleRuntime(
   db: DbConnection,
   registry: Registry,
+  syncSignal?: ToggleSyncSignal,
 ): Promise<GlobalFeatureToggleRuntime> {
-  const runtime = new GlobalFeatureToggleRuntime(db, registry);
+  const runtime = new GlobalFeatureToggleRuntime(db, registry, syncSignal);
   await runtime.initialize();
   return runtime;
 }

package/src/feature-toggles/toggle-sync-signal.ts

@@ -0,0 +1,57 @@
+import { createRedisPubSubSignal } from "@cosmicdrift/kumiko-framework/redis";
+import type { ToggleSyncSignal } from "./toggle-runtime";
+
+// Single fixed channel — unlike the SSE broker there's no per-tenant/
+// per-user variance to multiplex, every toggle flip is global.
+const TOGGLE_SYNC_CHANNEL = "kumiko:feature-toggles:cache-sync";
+
+export type RedisToggleSyncSignal = ToggleSyncSignal & {
+  // Not on ToggleSyncSignal — the in-memory/no-signal path (GlobalFeature
+  // ToggleRuntime without a signal) has nothing to release, but this one
+  // owns two live ioredis connections via the shared PubSubSignal.
+  close(): Promise<void>;
+};
+
+function isTogglePayload(value: unknown): value is { featureName: string; enabled: boolean } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { featureName?: unknown }).featureName === "string" &&
+    typeof (value as { enabled?: unknown }).enabled === "boolean"
+  );
+}
+
+// fw#2625: gives toggle-cache-sync the cross-replica transport its shared
+// dispatcher cursor needs — without this, only the one process that won
+// the shared cursor's toggle-set event would ever learn about a flip.
+// Same REDIS_URL-gated assumption as the SSE broker: a deployment with
+// replicas > 1 is expected to set REDIS_URL, so app-boot code should build
+// this only when REDIS_URL is present and pass it into
+// createFeatureToggleRuntime.
+export function createRedisToggleSyncSignal(redisUrl: string): RedisToggleSyncSignal {
+  const signal = createRedisPubSubSignal({
+    redisUrl,
+    channelPattern: TOGGLE_SYNC_CHANNEL,
+    label: "feature-toggles",
+  });
+
+  return {
+    publish(featureName, enabled) {
+      signal.publish(TOGGLE_SYNC_CHANNEL, { featureName, enabled });
+    },
+    onMessage(listener) {
+      signal.onMessage((_channel, payload) => {
+        if (!isTogglePayload(payload)) {
+          // biome-ignore lint/suspicious/noConsole: ops-visible fallback — no ctx.log in a raw PubSubSignal handler.
+          console.error(
+            `[kumiko:feature-toggles] dropping malformed cache-sync message on "${TOGGLE_SYNC_CHANNEL}"`,
+          );
+          // skip: malformed message already logged above, nothing to apply
+          return;
+        }
+        listener(payload.featureName, payload.enabled);
+      });
+    },
+    close: signal.close,
+  };
+}

package/src/notes-history/__tests__/notes-history-ownership.integration.test.ts

@@ -0,0 +1,202 @@
+// H.2 — row-level READ ownership for note-entry. Before this fix,
+// noteEntryEntity had no `access`, so buildOwnershipClause always returned
+// PASS_CLAUSE and any dispatch-eligible user could list every note in the
+// tenant, including notes on host entities they can't otherwise see.
+//
+// This is also the framework's first production exercise of a `where`-rule
+// WITH A SUBQUERY (existing ownership tests only use a literal
+// `sqlText: "custom_expr_42 = 1"`), so the scenario is built to genuinely
+// stress shiftParams: the ownership fragment's `$N` placeholder must be
+// renumbered past the tenant-scope filter's already-consumed slots
+// (event-store-executor-read.ts), not just happen to work at `$1`.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { NotesHistoryHandlers, NotesHistoryQueries } from "../constants";
+import { createNoteEntryEntity, noteEntryEntity } from "../entity";
+import { createNotesHistoryFeature } from "../feature";
+
+// Minimal fixture standing in for a real host projection: which team a host
+// entity (identified by entityId) belongs to. A real feature would source
+// this from its own read-model — this table exists only to give the
+// where-rule's subquery something real to join against.
+const TEAMS_TABLE = "notes_ownership_test_teams";
+
+const teamOwnership: NonNullable<EntityDefinition["access"]> = {
+  read: {
+    TenantMember: {
+      kind: "where",
+      where: (user, ctx) => ({
+        // Qualify the outer reference with ctx.tableName — the subquery's own
+        // `t.entity_id` column would otherwise shadow an unqualified bare
+        // `entity_id`, since Postgres resolves unqualified names to the
+        // innermost scope first. Confirmed by a raw-SQL repro during test
+        // development: an unqualified reference silently turned this into a
+        // self-join tautology (`t.entity_id = t.entity_id`), matching every
+        // row regardless of team.
+        sqlText: `EXISTS (SELECT 1 FROM ${TEAMS_TABLE} t WHERE t.entity_id = ${ctx.tableName}.entity_id AND t.team_id = $${ctx.paramStart})`,
+        params: [user.claims?.["team"] ?? null],
+      }),
+    },
+  },
+};
+
+type TestUser = ReturnType<typeof createTestUser>;
+
+let scopedStack: TestStack;
+let defaultStack: TestStack;
+
+// Same tenant, different team claim — the ownership rule (not tenant
+// scoping) is what must separate them.
+const userA: TestUser = createTestUser({
+  id: 20,
+  roles: ["TenantMember"],
+  claims: { team: "team-a" },
+});
+const userB: TestUser = createTestUser({
+  id: 21,
+  roles: ["TenantMember"],
+  claims: { team: "team-b" },
+});
+
+beforeAll(async () => {
+  scopedStack = await setupTestStack({
+    features: [createNotesHistoryFeature({ ownership: teamOwnership })],
+  });
+  await unsafeCreateEntityTable(scopedStack.db, createNoteEntryEntity(teamOwnership));
+  await createEventsTable(scopedStack.db);
+  await asRawClient(scopedStack.db).unsafe(
+    `CREATE TABLE IF NOT EXISTS ${TEAMS_TABLE} (entity_id text PRIMARY KEY, team_id text NOT NULL)`,
+  );
+
+  // Regression control, dedicated stack (mirrors tags.integration.test.ts's
+  // openStack/defaultStack): a plain (unscoped) mount of the SAME feature,
+  // used to prove the 0-rows result below is the ownership rule doing real
+  // work, not an empty table or a broken query.
+  defaultStack = await setupTestStack({ features: [createNotesHistoryFeature()] });
+  await unsafeCreateEntityTable(defaultStack.db, noteEntryEntity);
+  await createEventsTable(defaultStack.db);
+});
+
+afterAll(async () => {
+  await scopedStack.cleanup();
+  await defaultStack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(scopedStack.db).unsafe("DELETE FROM kumiko_events");
+  await asRawClient(scopedStack.db).unsafe("DELETE FROM read_note_entries");
+  await asRawClient(scopedStack.db).unsafe(`DELETE FROM ${TEAMS_TABLE}`);
+  await asRawClient(defaultStack.db).unsafe("DELETE FROM kumiko_events");
+  await asRawClient(defaultStack.db).unsafe("DELETE FROM read_note_entries");
+});
+
+async function addNote(stack: TestStack, entityId: string, user: TestUser): Promise<void> {
+  await stack.http.writeOk(
+    NotesHistoryHandlers.addNote,
+    { entityType: "project", entityId, body: "note" },
+    user,
+  );
+}
+
+async function listNotes(
+  stack: TestStack,
+  user: TestUser,
+  filter?: { field: string; op: "eq"; value: unknown },
+): Promise<Array<Record<string, unknown>>> {
+  const res = await stack.http.queryOk<{ rows: Array<Record<string, unknown>> }>(
+    NotesHistoryQueries.noteList,
+    filter ? { filter } : {},
+    user,
+  );
+  return res.rows;
+}
+
+describe("notes-history integration — row ownership (where-rule)", () => {
+  test("a team-scoped where-rule limits list() to the caller's team, with a filter applied", async () => {
+    // Both notes are authored by the SAME user (A), in the SAME tenant, both
+    // rows exist in TEAMS_TABLE — the only thing that can tell them apart is
+    // team_id. This is the discriminator that rules out both failure modes a
+    // weaker test would miss: a broken shiftParams (team_id compared against
+    // the tenant UUID or nothing → everyone sees 0) and a trivially-true
+    // subquery (EXISTS matches regardless of team_id → everyone sees both).
+    await addNote(scopedStack, "proj-1", userA); // will be team-a
+    await addNote(scopedStack, "proj-9", userA); // will be team-b — same author, different team
+    await asRawClient(scopedStack.db).unsafe(
+      `INSERT INTO ${TEAMS_TABLE} (entity_id, team_id) VALUES ($1, $2), ($3, $4)`,
+      ["proj-1", "team-a", "proj-9", "team-b"],
+    );
+
+    // User B (different team) sees nothing, even filtered down to the exact row.
+    expect(
+      await listNotes(scopedStack, userB, { field: "entityId", op: "eq", value: "proj-1" }),
+    ).toHaveLength(0);
+
+    // User A (own team) sees it. This is the real shiftParams exercise: the
+    // ownership fragment's `$N` is emitted starting at ctx.paramStart, then
+    // shifted again by the outer query's already-consumed tenant-scope
+    // params (2) plus the filter param (1) — if that arithmetic were wrong,
+    // A would ALSO see 0 rows instead of comparing team_id against garbage.
+    const ownRows = await listNotes(scopedStack, userA, {
+      field: "entityId",
+      op: "eq",
+      value: "proj-1",
+    });
+    expect(ownRows).toHaveLength(1);
+    expect(ownRows[0]?.["body"]).toBe("note");
+
+    // Unfiltered: A authored BOTH notes, but must see only the team-a one —
+    // proves the rule filters by team_id, not by authorship or a trivially-true
+    // subquery (which would return both).
+    const aRows = await listNotes(scopedStack, userA);
+    expect(aRows).toHaveLength(1);
+    expect(aRows[0]?.["entityId"]).toBe("proj-1");
+
+    // B authored NEITHER note, yet must see exactly the team-b one — proves
+    // the rule grants access by team membership, not by who wrote the row.
+    const bRows = await listNotes(scopedStack, userB);
+    expect(bRows).toHaveLength(1);
+    expect(bRows[0]?.["entityId"]).toBe("proj-9");
+  });
+
+  test("the same data on an unscoped mount leaks across teams (regression control)", async () => {
+    await addNote(defaultStack, "proj-1", userA);
+    // No ownership option on this stack's feature — the pre-fix behavior.
+    // Proves the 0-rows result above comes from the ownership rule, not
+    // from an unrelated empty-table/broken-query artifact.
+    expect(await listNotes(defaultStack, userB)).toHaveLength(1);
+  });
+
+  test("no explicit filter — ownership fragment still shifts correctly against the bare tenant scope", async () => {
+    await addNote(scopedStack, "proj-2", userA);
+    await asRawClient(scopedStack.db).unsafe(
+      `INSERT INTO ${TEAMS_TABLE} (entity_id, team_id) VALUES ($1, $2)`,
+      ["proj-2", "team-a"],
+    );
+
+    expect(await listNotes(scopedStack, userB)).toHaveLength(0);
+    expect(await listNotes(scopedStack, userA)).toHaveLength(1);
+  });
+});
+
+describe("notes-history — boot guard rejects a where-rule in ownership.write", () => {
+  test("createNotesHistoryFeature throws instead of shipping a create()-time landmine", () => {
+    expect(() =>
+      createNotesHistoryFeature({
+        ownership: {
+          write: {
+            TenantMember: { kind: "where", where: () => ({ sqlText: "1=1", params: [] }) },
+          },
+        },
+      }),
+    ).toThrow(/ownership\.write must not contain a.*where/);
+  });
+});