@cosmicdrift/kumiko-bundled-features 0.244.0 → 0.246.0

package/src/folders/handlers/set-folder.write.ts

@@ -1,5 +1,6 @@
 import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { parentRowIsVisible } from "../../shared";
 import { folderAssignmentAggregateId } from "../aggregate-id";
 import { DEFAULT_FOLDER_ACCESS } from "../constants";
 import { folderAssignmentExecutor, folderExecutor } from "../executor";
@@ -23,6 +24,11 @@ import { type SetFolderPayload, setFolderPayloadSchema } from "../schemas";
 // Referential integrity: there is no FK (event-sourced, no JOIN), so we verify
 // the target folder exists before writing — a malformed call with an unknown
 // folderId would otherwise point an entity at a phantom folder.
+//
+// Host reference: entityType/entityId are never trusted client input either —
+// the aggregate-id is tenant-scoped, so this is not a cross-tenant hole, but
+// without the check any dispatch-eligible tenant user could file an object they
+// are not allowed to read. See shared/parent-visibility.ts.
 export function createSetFolderHandler(
   access: AccessRule = DEFAULT_FOLDER_ACCESS,
 ): WriteHandlerDef {
@@ -34,6 +40,24 @@ export function createSetFolderHandler(
       "Files a host entity into one existing folder and moves it out of whatever folder it was in, since an entity belongs to at most one folder; use it for both the first filing and every later move.",
     handler: async (event, ctx) => {
       const payload = event.payload as SetFolderPayload; // @cast-boundary engine-payload
+      // entityType/entityId are client input: the caller must be able to see
+      // the host row through that entity's own read path (tenant scope plus its
+      // `access.read` ownership) before its assignment row may be written.
+      // Checked FIRST, ahead of every lookup below, so a denied caller can't tell
+      // an invisible parent apart from a missing assignment or an unknown folder —
+      // every path answers with the same NotFoundError.
+      if (
+        !(await parentRowIsVisible(
+          ctx.registry,
+          payload.entityType,
+          payload.entityId,
+          event.user,
+          ctx.db,
+        ))
+      ) {
+        return writeFailure(new NotFoundError(payload.entityType, payload.entityId));
+      }
+
       const id = folderAssignmentAggregateId(
         event.user.tenantId,
         payload.entityType,

package/src/folders-user-data/__tests__/hooks.integration.test.ts

@@ -3,8 +3,15 @@
 // via selectMany without an isDeleted filter — folderAssignmentEntity is
 // softDelete: true, so a cleared assignment (clear-folder) still had a row
 // in read_folder_assignments and rode along in the export.
+//
+// set-folder/clear-folder verify that entityType names a registered entity and
+// that the host row is visible to the caller, so the two credits below are a
+// real registered fixture. The assertion is about the export hook's isDeleted
+// filter, not about ownership — the fixture is deliberately unrestricted.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   createTestUser,
@@ -16,14 +23,31 @@ import { createFoldersFeature, FoldersHandlers } from "../../folders";
 import { folderAssignmentEntity, folderEntity } from "../../folders/entity";
 import { folderAssignmentExportHook } from "../hooks";
 
+const CREDIT_TABLE = "folders_export_test_credits";
+const creditEntity = createEntity({
+  table: CREDIT_TABLE,
+  fields: { name: createTextField({ required: true, maxLength: 64 }) },
+});
+const hostFixturesFeature = defineFeature("folders-export-test-host-fixtures", (r) => {
+  r.entity("credit", creditEntity);
+});
+
+const CREDIT_KEPT = "d0000000-0000-4000-8000-000000000001";
+const CREDIT_CLEARED = "d0000000-0000-4000-8000-000000000002";
+
 let stack: TestStack;
 const admin = createTestUser({ roles: ["TenantAdmin"] });
 
 beforeAll(async () => {
-  stack = await setupTestStack({ features: [createFoldersFeature()] });
+  stack = await setupTestStack({ features: [createFoldersFeature(), hostFixturesFeature] });
   await unsafeCreateEntityTable(stack.db, folderEntity);
   await unsafeCreateEntityTable(stack.db, folderAssignmentEntity);
+  await unsafeCreateEntityTable(stack.db, creditEntity);
   await createEventsTable(stack.db);
+  await asRawClient(stack.db).unsafe(
+    `INSERT INTO ${CREDIT_TABLE} (id, tenant_id, name) VALUES ($1, $3, 'kept'), ($2, $3, 'cleared')`,
+    [CREDIT_KEPT, CREDIT_CLEARED, admin.tenantId],
+  );
 });
 
 afterAll(async () => {
@@ -40,18 +64,18 @@ describe("folderAssignmentExportHook", () => {
 
     await stack.http.writeOk(
       FoldersHandlers.setFolder,
-      { folderId: folder.id, entityType: "credit", entityId: "credit-kept" },
+      { folderId: folder.id, entityType: "credit", entityId: CREDIT_KEPT },
       admin,
     );
     await stack.http.writeOk(
       FoldersHandlers.setFolder,
-      { folderId: folder.id, entityType: "credit", entityId: "credit-cleared" },
+      { folderId: folder.id, entityType: "credit", entityId: CREDIT_CLEARED },
       admin,
     );
     // clear-folder soft-deletes the assignment row (isDeleted: true).
     await stack.http.writeOk(
       FoldersHandlers.clearFolder,
-      { entityType: "credit", entityId: "credit-cleared" },
+      { entityType: "credit", entityId: CREDIT_CLEARED },
       admin,
     );
 
@@ -64,7 +88,7 @@ describe("folderAssignmentExportHook", () => {
 
     expect(snippet).not.toBeNull();
     const entityIds = (snippet?.rows ?? []).map((r) => r["entityId"]);
-    expect(entityIds).toContain("credit-kept");
-    expect(entityIds).not.toContain("credit-cleared");
+    expect(entityIds).toContain(CREDIT_KEPT);
+    expect(entityIds).not.toContain(CREDIT_CLEARED);
   });
 });

package/src/notes-history/__tests__/add-note-author-name-kms.integration.test.ts

@@ -5,15 +5,25 @@
 // KMS adapter so the round-trip is proven end-to-end, not assumed from a
 // no-op-encrypt test env — a later refactor that silently reintroduces the
 // raw UUID or gets stuck on the placeholder would fail this.
+//
+// fw#2627 made add-note's parent-visibility check unconditional, so a
+// minimal `contact` fixture entity (PASS_CLAUSE) is mounted below and seeded
+// with the one row this file writes a note to — orthogonal to what this file
+// actually tests (authorName stamping).
 
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configurePiiSubjectKms,
   InMemoryKmsAdapter,
   isPiiCiphertext,
 } from "@cosmicdrift/kumiko-framework/crypto";
-import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  type SessionUser,
+} from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
   type TestStack,
@@ -30,6 +40,16 @@ import { createNotesHistoryFeature } from "../feature";
 const notesHistoryFeature = createNotesHistoryFeature();
 const tenantId = testTenantId(1);
 
+const CONTACT_TABLE = "notes_kms_test_contacts";
+const contactEntity = createEntity({
+  table: CONTACT_TABLE,
+  fields: { name: createTextField({ required: true, maxLength: 64 }) },
+});
+const contactFixtureFeature = defineFeature("notes-kms-test-contact-fixture", (r) => {
+  r.entity("contact", contactEntity);
+});
+const CONTACT_KMS_AUTHOR = "40000000-0000-4000-8000-000000000001";
+
 let stack: TestStack;
 
 function memberUser(userId: string): SessionUser {
@@ -37,9 +57,14 @@ function memberUser(userId: string): SessionUser {
 }
 
 beforeAll(async () => {
-  stack = await setupTestStack({ features: [notesHistoryFeature] });
+  stack = await setupTestStack({ features: [notesHistoryFeature, contactFixtureFeature] });
   await unsafeCreateEntityTable(stack.db, noteEntryEntity);
   await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, contactEntity);
+  await asRawClient(stack.db).unsafe(
+    `INSERT INTO ${CONTACT_TABLE} (id, tenant_id, name) VALUES ($1, $2, $3)`,
+    [CONTACT_KMS_AUTHOR, tenantId, CONTACT_KMS_AUTHOR],
+  );
 });
 
 afterAll(async () => {
@@ -70,13 +95,13 @@ describe("add-note — authorName stamped from the writer's own user row", () =>
 
     const { id: noteId } = await stack.http.writeOk<{ id: string }>(
       NotesHistoryHandlers.addNote,
-      { entityType: "contact", entityId: "contact-kms-author", body: "Called back." },
+      { entityType: "contact", entityId: CONTACT_KMS_AUTHOR, body: "Called back." },
       memberUser(userId),
     );
 
     const { rows } = await stack.http.queryOk<{ rows: Array<Record<string, unknown>> }>(
       NotesHistoryQueries.noteList,
-      { filter: { field: "entityId", op: "eq", value: "contact-kms-author" } },
+      { filter: { field: "entityId", op: "eq", value: CONTACT_KMS_AUTHOR } },
       memberUser(userId),
     );
 

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

@@ -9,10 +9,24 @@
 // 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`.
+//
+// fw#2627 made add-note's parent-visibility check unconditional: entityType
+// must now name a registered entity, and the row must exist and be visible
+// to the caller. This file tests NOTE-level ownership, not parent-level, so
+// the fixture `project` entity below is deliberately registered with NO
+// `access` (PASS_CLAUSE) — any tenant member can write a note onto it — and
+// every project row used below is inserted before its add-note call, so the
+// parent-visibility check never interferes with what this file is actually
+// proving.
 
 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 {
+  createEntity,
+  createTextField,
+  defineFeature,
+  type EntityDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   createTestUser,
@@ -49,6 +63,23 @@ const teamOwnership: NonNullable<EntityDefinition["access"]> = {
   },
 };
 
+// The `project` parent entity add-note now always checks for. No `access` —
+// PASS_CLAUSE — so it never gates on its own; this file's team split is
+// entirely on the note-entry side (teamOwnership above).
+const PROJECT_TABLE = "notes_ownership_test_projects";
+const projectEntity: EntityDefinition = createEntity({
+  table: PROJECT_TABLE,
+  fields: { name: createTextField({ required: true, maxLength: 64 }) },
+});
+const projectFixtureFeature = defineFeature("notes-ownership-test-project-fixture", (r) => {
+  r.entity("project", projectEntity);
+});
+
+const PROJ_1 = "20000000-0000-4000-8000-000000000001";
+const PROJ_9 = "20000000-0000-4000-8000-000000000009";
+const PROJ_2 = "20000000-0000-4000-8000-000000000002";
+const PROJ_B = "20000000-0000-4000-8000-00000000000b";
+
 type TestUser = ReturnType<typeof createTestUser>;
 
 let scopedStack: TestStack;
@@ -67,23 +98,42 @@ const userB: TestUser = createTestUser({
   claims: { team: "team-b" },
 });
 
+async function insertProjects(
+  stack: TestStack,
+  tenantId: string,
+  ids: readonly string[],
+): Promise<void> {
+  for (const id of ids) {
+    await asRawClient(stack.db).unsafe(
+      `INSERT INTO ${PROJECT_TABLE} (id, tenant_id, name) VALUES ($1, $2, $3)`,
+      [id, tenantId, id],
+    );
+  }
+}
+
 beforeAll(async () => {
   scopedStack = await setupTestStack({
-    features: [createNotesHistoryFeature({ ownership: teamOwnership })],
+    features: [createNotesHistoryFeature({ ownership: teamOwnership }), projectFixtureFeature],
   });
   await unsafeCreateEntityTable(scopedStack.db, createNoteEntryEntity(teamOwnership));
+  await unsafeCreateEntityTable(scopedStack.db, projectEntity);
   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)`,
   );
+  await insertProjects(scopedStack, userA.tenantId, [PROJ_1, PROJ_9, PROJ_2]);
 
   // 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()] });
+  defaultStack = await setupTestStack({
+    features: [createNotesHistoryFeature(), projectFixtureFeature],
+  });
   await unsafeCreateEntityTable(defaultStack.db, noteEntryEntity);
+  await unsafeCreateEntityTable(defaultStack.db, projectEntity);
   await createEventsTable(defaultStack.db);
+  await insertProjects(defaultStack, userA.tenantId, [PROJ_1]);
 });
 
 afterAll(async () => {
@@ -128,16 +178,16 @@ describe("notes-history integration — row ownership (where-rule)", () => {
     // 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 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"],
+      [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" }),
+      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
@@ -148,7 +198,7 @@ describe("notes-history integration — row ownership (where-rule)", () => {
     const ownRows = await listNotes(scopedStack, userA, {
       field: "entityId",
       op: "eq",
-      value: "proj-1",
+      value: PROJ_1,
     });
     expect(ownRows).toHaveLength(1);
     expect(ownRows[0]?.["body"]).toBe("note");
@@ -158,17 +208,17 @@ describe("notes-history integration — row ownership (where-rule)", () => {
     // subquery (which would return both).
     const aRows = await listNotes(scopedStack, userA);
     expect(aRows).toHaveLength(1);
-    expect(aRows[0]?.["entityId"]).toBe("proj-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");
+    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);
+    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.
@@ -176,10 +226,10 @@ describe("notes-history integration — row ownership (where-rule)", () => {
   });
 
   test("no explicit filter — ownership fragment still shifts correctly against the bare tenant scope", async () => {
-    await addNote(scopedStack, "proj-2", userA);
+    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"],
+      [PROJ_2, "team-a"],
     );
 
     expect(await listNotes(scopedStack, userB)).toHaveLength(0);
@@ -187,8 +237,88 @@ describe("notes-history integration — row ownership (where-rule)", () => {
   });
 });
 
+describe("unqualified where-rule fails closed, not open (fw#2639)", () => {
+  // Same shape as `teamOwnership` above, but the subquery's inner reference
+  // is left unqualified (`entity_id` instead of `t.entity_id`/`${ctx.tableName}.entity_id`).
+  // Postgres binds the unqualified name to the innermost table (`t`) first,
+  // so `t.entity_id = entity_id` silently becomes `t.entity_id = t.entity_id`
+  // — a self-join tautology that matches every row regardless of team.
+  const unqualifiedOwnership: NonNullable<EntityDefinition["access"]> = {
+    read: {
+      TenantMember: {
+        kind: "where",
+        where: (user, ctx) => {
+          const team = user.claims?.["team"];
+          // Boot probe has no claims and bails out here; the runtime lint in
+          // ruleToFragment is what must catch the unqualified reference.
+          if (typeof team !== "string") throw new Error("team claim required");
+          return {
+            sqlText: `EXISTS (SELECT 1 FROM ${TEAMS_TABLE} t WHERE t.entity_id = entity_id AND t.team_id = $${ctx.paramStart})`,
+            params: [team],
+          };
+        },
+      },
+    },
+  };
+
+  let unqualifiedStack: TestStack;
+
+  beforeAll(async () => {
+    // Reaching this point at all proves the boot guard doesn't false-positive
+    // on this rule: PROBE_USER carries no claims, so `where()` throws before
+    // the lint ever sees the bad SQL, and boot-validator/ownership.ts's
+    // probeWhereRule swallows that and moves on.
+    //
+    // add-note's parent-visibility check is unconditional since fw#2627, so
+    // this stack also needs the PASS_CLAUSE project fixture mounted — this
+    // block otherwise stays focused on the note-entry ownership rule.
+    unqualifiedStack = await setupTestStack({
+      features: [
+        createNotesHistoryFeature({ ownership: unqualifiedOwnership }),
+        projectFixtureFeature,
+      ],
+    });
+    await unsafeCreateEntityTable(unqualifiedStack.db, createNoteEntryEntity(unqualifiedOwnership));
+    await unsafeCreateEntityTable(unqualifiedStack.db, projectEntity);
+    await createEventsTable(unqualifiedStack.db);
+    await asRawClient(unqualifiedStack.db).unsafe(
+      `CREATE TABLE IF NOT EXISTS ${TEAMS_TABLE} (entity_id text PRIMARY KEY, team_id text NOT NULL)`,
+    );
+    await insertProjects(unqualifiedStack, userB.tenantId, [PROJ_B]);
+  });
+
+  afterAll(async () => {
+    await unqualifiedStack.cleanup();
+  });
+
+  test("list() fails closed instead of leaking userB's row to userA", async () => {
+    await addNote(unqualifiedStack, PROJ_B, userB);
+    await asRawClient(unqualifiedStack.db).unsafe(
+      `INSERT INTO ${TEAMS_TABLE} (entity_id, team_id) VALUES ($1, $2)`,
+      [PROJ_B, "team-b"],
+    );
+
+    // Pre-fix: this query returned HTTP 200 with userB's row (the tautology
+    // matches every row) — queryErr would throw "Expected query to fail but
+    // it succeeded". Post-fix: the runtime lint in ruleToFragment throws
+    // before the query ever runs, so the request fails loud instead of
+    // leaking. Asserting the concrete status (not just "isSuccess: false")
+    // documents exactly how it fails: an uncaught Error auto-wraps into
+    // InternalError (500), not a handled 4xx.
+    const error = await unqualifiedStack.http.queryErr(NotesHistoryQueries.noteList, {}, userA);
+    expect(error.httpStatus).toBe(500);
+    expect(error.code).toBe("internal_error");
+  });
+
+  // Green-path twin: `scopedStack` above (built with the correctly-qualified
+  // `teamOwnership` rule) already proves the lint doesn't reject every
+  // subquery rule — its first test asserts userA sees exactly its own
+  // team's row via HTTP 200 and never userB's. Relying on that coverage
+  // instead of duplicating a second correctly-qualified stack here.
+});
+
 describe("notes-history — boot guard rejects a where-rule in ownership.write", () => {
-  test("createNotesHistoryFeature throws instead of shipping a create()-time landmine", () => {
+  test("createNotesHistoryFeature throws instead of shipping a deny-only ownership map", () => {
     expect(() =>
       createNotesHistoryFeature({
         ownership: {

package/src/notes-history/__tests__/notes-history-parent-visibility.integration.test.ts

@@ -0,0 +1,225 @@
+// fw#2627 — add-note previously trusted entityType/entityId straight from the
+// client, so any dispatch-eligible tenant user could attach a note to a
+// parent object they had no read access to. The parent-visibility check is
+// unconditional (default-on, no opt-in): entityType must name a registered
+// entity, and the row must be visible through that entity's own read path
+// (tenant scope plus its `access.read` ownership) before add-note accepts
+// the write — on every mount, `parents` or not. `parents`, when set, only
+// narrows FURTHER to an allowlist of permitted parent entity names; it is
+// not what turns the check on (see `openStack` tests below, which mount
+// notes-history with no `parents` at all and still enforce the check).
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  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 } from "../constants";
+import { createNoteEntryEntity } from "../entity";
+import { createNotesHistoryFeature } from "../feature";
+
+const PROJECT_TABLE = "notes_pv_test_projects";
+
+// Team-scoped read ownership on the parent entity itself — the caller sees a
+// project row only if their `team` claim matches the row's team_id.
+const projectOwnership: NonNullable<EntityDefinition["access"]> = {
+  read: {
+    TenantMember: {
+      kind: "where",
+      where: (user, ctx) => ({
+        sqlText: `${ctx.tableName}.team_id = $${ctx.paramStart}`,
+        params: [user.claims?.["team"] ?? null],
+      }),
+    },
+  },
+};
+
+function createProjectEntity(access?: EntityDefinition["access"]): EntityDefinition {
+  return createEntity({
+    table: PROJECT_TABLE,
+    fields: {
+      teamId: createTextField({ required: true, maxLength: 64 }),
+      name: createTextField({ required: true, maxLength: 64 }),
+    },
+    access,
+  });
+}
+
+const guardedProjectEntity = createProjectEntity(projectOwnership);
+
+// A second registered entity, deliberately left OUT of the `parents`
+// allowlist below — proves the allowlist rejects a real, registered entity
+// too, not just made-up names.
+const contactEntity = createEntity({
+  table: "notes_pv_test_contacts",
+  fields: { name: createTextField({ required: true, maxLength: 64 }) },
+});
+
+const fixturesFeature = defineFeature("notes-pv-test-fixtures", (r) => {
+  r.entity("project", guardedProjectEntity);
+  r.entity("contact", contactEntity);
+});
+
+type TestUser = ReturnType<typeof createTestUser>;
+
+// Same tenant, different team claim — mirrors the ownership integration test.
+const userA: TestUser = createTestUser({
+  id: 40,
+  roles: ["TenantMember"],
+  claims: { team: "team-a" },
+});
+const userB: TestUser = createTestUser({
+  id: 41,
+  roles: ["TenantMember"],
+  claims: { team: "team-b" },
+});
+
+const PROJECT_A = "a0000000-0000-4000-8000-000000000001";
+// A second team-a project, dedicated to the cross-team-denial case so its
+// note-count stays independent of PROJECT_A's.
+const PROJECT_A2 = "a0000000-0000-4000-8000-000000000002";
+// openStack-only team-a project row — never reused as PROJECT_A2 so the two
+// stacks' tests stay order-independent.
+const PROJECT_OPEN = "a0000000-0000-4000-8000-000000000009";
+
+let guardedStack: TestStack;
+let openStack: TestStack;
+
+beforeAll(async () => {
+  guardedStack = await setupTestStack({
+    features: [createNotesHistoryFeature({ parents: ["project"] }), fixturesFeature],
+  });
+  await unsafeCreateEntityTable(guardedStack.db, guardedProjectEntity);
+  await unsafeCreateEntityTable(guardedStack.db, createNoteEntryEntity());
+  await createEventsTable(guardedStack.db);
+  await asRawClient(guardedStack.db).unsafe(
+    `INSERT INTO ${PROJECT_TABLE} (id, tenant_id, team_id, name) VALUES
+       ($1, $2, 'team-a', 'Project A'),
+       ($3, $2, 'team-a', 'Project A2')`,
+    [PROJECT_A, userA.tenantId, PROJECT_A2],
+  );
+
+  // Unguarded mount: the SAME feature with no `parents` at all — proves the
+  // parent-visibility check itself is default-on, not something `parents`
+  // switches on.
+  openStack = await setupTestStack({
+    features: [createNotesHistoryFeature(), fixturesFeature],
+  });
+  await unsafeCreateEntityTable(openStack.db, guardedProjectEntity);
+  await unsafeCreateEntityTable(openStack.db, createNoteEntryEntity());
+  await createEventsTable(openStack.db);
+  await asRawClient(openStack.db).unsafe(
+    `INSERT INTO ${PROJECT_TABLE} (id, tenant_id, team_id, name) VALUES ($1, $2, 'team-a', 'Project Open')`,
+    [PROJECT_OPEN, userA.tenantId],
+  );
+});
+
+afterAll(async () => {
+  await guardedStack.cleanup();
+  await openStack.cleanup();
+});
+
+async function addNote(
+  stack: TestStack,
+  entityType: string,
+  entityId: string,
+  user: TestUser,
+): Promise<{ id: string }> {
+  return stack.http.writeOk<{ id: string }>(
+    NotesHistoryHandlers.addNote,
+    { entityType, entityId, body: "note" },
+    user,
+  );
+}
+
+async function addNoteErr(stack: TestStack, entityType: string, entityId: string, user: TestUser) {
+  return stack.http.writeErr(
+    NotesHistoryHandlers.addNote,
+    { entityType, entityId, body: "note" },
+    user,
+  );
+}
+
+async function noteCountFor(stack: TestStack, entityId: string): Promise<number> {
+  const rows = await asRawClient(stack.db).unsafe<{ count: string }>(
+    `SELECT count(*)::text AS count FROM read_note_entries WHERE entity_id = $1`,
+    [entityId],
+  );
+  return Number(rows[0]?.count ?? "0");
+}
+
+describe("notes-history integration — add-note parent-visibility (parents option)", () => {
+  test("caller may note a parent row visible through the parent entity's own read path", async () => {
+    const result = await addNote(guardedStack, "project", PROJECT_A, userA);
+    expect(result.id).toBeTruthy();
+    expect(await noteCountFor(guardedStack, PROJECT_A)).toBe(1);
+  });
+
+  test("caller is denied noting a parent row from a foreign team while the same row is writable by its own team", async () => {
+    const err = await addNoteErr(guardedStack, "project", PROJECT_A2, userB);
+    expect(err.code).toBe("not_found");
+    expect(err.httpStatus).toBe(404);
+    expect(await noteCountFor(guardedStack, PROJECT_A2)).toBe(0);
+
+    // Positive control: PROJECT_A2 itself is writable — by its own team — so
+    // the deny above is the team-claim check, not some other rejection (e.g.
+    // a row that doesn't exist at all).
+    const result = await addNote(guardedStack, "project", PROJECT_A2, userA);
+    expect(result.id).toBeTruthy();
+    expect(await noteCountFor(guardedStack, PROJECT_A2)).toBe(1);
+  });
+
+  test("entityType outside the allowlist is denied even when it is a registered entity", async () => {
+    const err = await addNoteErr(
+      guardedStack,
+      "contact",
+      "c0000000-0000-4000-8000-000000000003",
+      userA,
+    );
+    expect(err.code).toBe("not_found");
+  });
+
+  test("entityType that is not registered anywhere is denied", async () => {
+    const err = await addNoteErr(guardedStack, "totally-unknown-entity", "x", userA);
+    expect(err.code).toBe("not_found");
+  });
+
+  test("a malformed entityId is denied cleanly, without poisoning the connection for later writes", async () => {
+    const err = await addNoteErr(guardedStack, "project", "not-a-uuid", userA);
+    expect(err.code).toBe("not_found");
+    expect(err.httpStatus).toBe(404);
+
+    // The stack must still be usable afterwards — proves the malformed id was
+    // rejected before it ever reached a query, not caught after a failed
+    // (and tx-poisoning) cast.
+    const result = await addNote(guardedStack, "project", PROJECT_A, userA);
+    expect(result.id).toBeTruthy();
+  });
+
+  test("on an unguarded mount (no `parents`), an unregistered entityType is still denied — the check is default-on", async () => {
+    const err = await addNoteErr(openStack, "totally-unknown-entity", "y", userA);
+    expect(err.code).toBe("not_found");
+  });
+
+  test("on an unguarded mount, a registered and visible parent still succeeds", async () => {
+    const result = await addNote(openStack, "project", PROJECT_OPEN, userA);
+    expect(result.id).toBeTruthy();
+    expect(await noteCountFor(openStack, PROJECT_OPEN)).toBe(1);
+  });
+
+  test("on an unguarded mount, a registered parent from a foreign team is still denied", async () => {
+    const err = await addNoteErr(openStack, "project", PROJECT_OPEN, userB);
+    expect(err.code).toBe("not_found");
+    expect(err.httpStatus).toBe(404);
+  });
+});