@cosmicdrift/kumiko-bundled-features 0.256.0 → 0.258.0

package/src/folders/__tests__/folders-read-gate.integration.test.ts

@@ -0,0 +1,179 @@
+// The read twin of folders-parent-visibility.integration.test.ts (fw#2766).
+// set-folder/clear-folder were gated against the host row's own read path, but
+// `folder-assignment:list` returned every membership row of the tenant — and
+// unlike tags/notes, folders had no `ownership` option at all, so there was no
+// opt-in lever either. The gate below is default-on.
+
+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 { FoldersHandlers, FoldersQueries } from "../constants";
+import { folderAssignmentEntity, folderEntity } from "../entity";
+import { createFoldersFeature } from "../feature";
+
+const PROJECT_TABLE = "folders_rg_test_projects";
+
+const teamScopedRead: NonNullable<EntityDefinition["access"]> = {
+  read: {
+    TenantMember: {
+      kind: "where",
+      where: (user, ctx) => ({
+        sqlText: `${ctx.tableName}.team_id = $${ctx.paramStart}`,
+        params: [user.claims?.["team"] ?? null],
+      }),
+    },
+  },
+};
+
+const projectEntity = createEntity({
+  table: PROJECT_TABLE,
+  fields: {
+    teamId: createTextField({
+      required: true,
+      maxLength: 64,
+      personal: false,
+      reason: "technical_reference",
+    }),
+  },
+  access: teamScopedRead,
+});
+
+const hostFixturesFeature = defineFeature("folders-rg-test-fixtures", (r) => {
+  r.entity("project", projectEntity);
+});
+
+type TestUser = ReturnType<typeof createTestUser>;
+
+const userA: TestUser = createTestUser({
+  id: 90,
+  roles: ["TenantMember"],
+  claims: { team: "team-a" },
+});
+const userB: TestUser = createTestUser({
+  id: 91,
+  roles: ["TenantMember"],
+  claims: { team: "team-b" },
+});
+
+const PROJECT_A = "e0000000-0000-4000-8000-00000000000a";
+const PROJECT_B = "e0000000-0000-4000-8000-00000000000b";
+const ORPHAN_HOST_ID = "e0000000-0000-4000-8000-0000000000ff";
+
+type AssignmentRow = { id: string; folderId: string; entityType: string; entityId: string };
+type Page = { rows: readonly AssignmentRow[]; nextCursor: string | null; total?: number };
+
+let stack: TestStack;
+let folderId: string;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createFoldersFeature({ access: { openToAll: true } }), hostFixturesFeature],
+  });
+  await unsafeCreateEntityTable(stack.db, folderEntity);
+  await unsafeCreateEntityTable(stack.db, folderAssignmentEntity);
+  await unsafeCreateEntityTable(stack.db, projectEntity);
+  await createEventsTable(stack.db);
+
+  await asRawClient(stack.db).unsafe(
+    `INSERT INTO ${PROJECT_TABLE} (id, tenant_id, team_id) VALUES ($1, $3, 'team-a'), ($2, $3, 'team-b')`,
+    [PROJECT_A, PROJECT_B, userA.tenantId],
+  );
+
+  const folder = await stack.http.writeOk<{ id: string }>(
+    FoldersHandlers.createFolder,
+    { name: "Shared" },
+    userA,
+  );
+  folderId = folder.id;
+
+  await stack.http.writeOk(
+    FoldersHandlers.setFolder,
+    { folderId, entityType: "project", entityId: PROJECT_A },
+    userA,
+  );
+  await stack.http.writeOk(
+    FoldersHandlers.setFolder,
+    { folderId, entityType: "project", entityId: PROJECT_B },
+    userB,
+  );
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function listAssignments(payload: Record<string, unknown>, user: TestUser): Promise<Page> {
+  return stack.http.queryOk<Page>(FoldersQueries.assignmentList, payload, user);
+}
+
+describe("folders read-gate", () => {
+  test("the owning team sees which folder its own project sits in", async () => {
+    const page = await listAssignments(
+      { filter: { field: "entityId", op: "eq", value: PROJECT_A } },
+      userA,
+    );
+    expect(page.rows).toHaveLength(1);
+    expect(page.rows[0]?.entityId).toBe(PROJECT_A);
+  });
+
+  test("a foreign team sees nothing there — folders never had an ownership opt-in", async () => {
+    const page = await listAssignments(
+      { filter: { field: "entityId", op: "eq", value: PROJECT_A }, totalCount: true },
+      userB,
+    );
+    expect(page.rows).toHaveLength(0);
+    expect(page.total).toBe(0);
+  });
+
+  test("listing a folder's contents shows only hosts the caller can read", async () => {
+    const forA = await listAssignments(
+      { filter: { field: "folderId", op: "eq", value: folderId }, totalCount: true },
+      userA,
+    );
+    expect(forA.rows.map((r) => r.entityId)).toEqual([PROJECT_A]);
+    expect(forA.total).toBe(1);
+
+    const forB = await listAssignments(
+      { filter: { field: "folderId", op: "eq", value: folderId }, totalCount: true },
+      userB,
+    );
+    expect(forB.rows.map((r) => r.entityId)).toEqual([PROJECT_B]);
+    expect(forB.total).toBe(1);
+  });
+
+  test("an assignment whose entityType names no registered entity is invisible to everyone", async () => {
+    const orphanId = "e0000000-0000-4000-8000-0000000000f1";
+    await asRawClient(stack.db).unsafe(
+      `INSERT INTO read_folder_assignments (id, tenant_id, folder_id, entity_type, entity_id, is_deleted)
+       VALUES ($1, $2, $3, 'not-a-registered-entity', $4, FALSE)`,
+      [orphanId, userA.tenantId, folderId, ORPHAN_HOST_ID],
+    );
+
+    for (const user of [userA, userB]) {
+      const page = await listAssignments(
+        { filter: { field: "entityId", op: "eq", value: ORPHAN_HOST_ID }, totalCount: true },
+        user,
+      );
+      expect(page.rows).toHaveLength(0);
+      expect(page.total).toBe(0);
+    }
+
+    const raw = await asRawClient(stack.db).unsafe<{ n: number }>(
+      "SELECT count(*)::int AS n FROM read_folder_assignments WHERE id = $1",
+      [orphanId],
+    );
+    expect(raw[0]?.n).toBe(1);
+  });
+});

package/src/folders/entity.ts

@@ -1,4 +1,8 @@
-import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntity,
+  createTextField,
+  type EntityDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
 
 // folder — per-tenant hierarchical catalog. Event-sourced (create/update/delete
 // via the standard executor); the framework projects `read_folders` from its own
@@ -39,30 +43,45 @@ export const folderEntity = createEntity({
 // Cross-entity views compose in the read-layer (no JOIN):
 //   - folder of an entity  → list assignments filter { field: "entityId", op: "eq" }
 //   - entities in a folder  → list assignments filter { field: "folderId", op: "eq" }
-export const folderAssignmentEntity = createEntity({
-  table: "read_folder_assignments",
-  description:
-    "The membership row recording which folder one host entity, addressed by entityType and entityId, is filed in. At most one row exists per entity, so filing it elsewhere changes this row's folderId rather than adding a second.",
-  softDelete: true,
-  fields: {
-    folderId: createTextField({
-      required: true,
-      maxLength: 64,
-      personal: false,
-      reason: "technical_reference",
-    }),
-    entityType: createTextField({
-      required: true,
-      maxLength: 64,
-      personal: false,
-      reason: "technical_reference",
-    }),
-    // Host entity ids are uuid/text; 128 covers uuid plus non-uuid text keys.
-    entityId: createTextField({
-      required: true,
-      maxLength: 128,
-      personal: false,
-      reason: "technical_reference",
-    }),
-  },
-});
+export function createFolderAssignmentEntity(
+  access?: EntityDefinition["access"],
+  parents?: readonly string[],
+) {
+  return createEntity({
+    table: "read_folder_assignments",
+    description:
+      "The membership row recording which folder one host entity, addressed by entityType and entityId, is filed in. At most one row exists per entity, so filing it elsewhere changes this row's folderId rather than adding a second.",
+    softDelete: true,
+    access,
+    // Declared unconditionally: the host-visibility gate is the default for
+    // both paths, and `parents` only narrows which hosts are admissible.
+    parentRef: {
+      entityTypeField: "entityType",
+      entityIdField: "entityId",
+      ...(parents !== undefined && { allowedTypes: parents }),
+    },
+    fields: {
+      folderId: createTextField({
+        required: true,
+        maxLength: 64,
+        personal: false,
+        reason: "technical_reference",
+      }),
+      entityType: createTextField({
+        required: true,
+        maxLength: 64,
+        personal: false,
+        reason: "technical_reference",
+      }),
+      // Host entity ids are uuid/text; 128 covers uuid plus non-uuid text keys.
+      entityId: createTextField({
+        required: true,
+        maxLength: 128,
+        personal: false,
+        reason: "technical_reference",
+      }),
+    },
+  });
+}
+
+export const folderAssignmentEntity = createFolderAssignmentEntity();

package/src/folders/feature.ts

@@ -22,10 +22,12 @@ import {
   defineEntityListHandler,
   defineEntityUpdateHandler,
   defineFeature,
+  type EntityDefinition,
   type FeatureRegistrar,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { hasWhereRule } from "../shared";
 import { DEFAULT_FOLDER_ACCESS, FOLDERS_FEATURE_NAME } from "./constants";
-import { folderAssignmentEntity, folderEntity } from "./entity";
+import { createFolderAssignmentEntity, folderEntity } from "./entity";
 import { createClearFolderHandler } from "./handlers/clear-folder.write";
 import { createDeleteFolderHandler } from "./handlers/delete-folder.write";
 import { createSetFolderHandler } from "./handlers/set-folder.write";
@@ -41,6 +43,8 @@ function registerFolders(
   r: FeatureRegistrar<typeof FOLDERS_FEATURE_NAME>,
   access: AccessRule,
   toggleable: FoldersToggleable | undefined,
+  ownership: EntityDefinition["access"] | undefined,
+  parents: readonly string[] | undefined,
 ): void {
   r.describe(
     "Generic, host-agnostic hierarchical folders for any entity. Owns two event-sourced entities — the per-tenant `folder` tree (`read_folders`, self-referential via parentId) and SINGLE-membership `folder-assignment` rows keyed by (entityType, entityId) (`read_folder_assignments`) — so filing an entity adds NO column to the host and needs no relational pivot or JOIN. The folder catalog uses the generic entity handlers (create, update [= rename, optimistic-locked], delete, list, detail); set-folder puts/moves an entity into a folder (one folder per entity) and clear-folder unfiles it (both idempotent). Read which folder an entity is in, or which entities a folder holds, by listing `folder-assignment` filtered on `entityId` or `folderId`. Every path uses one access rule — adopt the host's model with createFoldersFeature({ access: { openToAll: true } }) or pin roles. Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
@@ -53,6 +57,7 @@ function registerFolders(
 
   if (toggleable !== undefined) r.toggleable(toggleable);
 
+  const folderAssignmentEntity = createFolderAssignmentEntity(ownership, parents);
   r.entity("folder", folderEntity);
   r.entity("folder-assignment", folderAssignmentEntity);
 
@@ -103,7 +108,7 @@ function registerFolders(
 }
 
 export const foldersFeature = defineFeature(FOLDERS_FEATURE_NAME, (r) =>
-  registerFolders(r, DEFAULT_FOLDER_ACCESS, undefined),
+  registerFolders(r, DEFAULT_FOLDER_ACCESS, undefined, undefined, undefined),
 );
 
 export type FoldersFeatureOptions = {
@@ -119,6 +124,28 @@ export type FoldersFeatureOptions = {
    *  `default` applies when no toggle/tier override exists — use { default: false }
    *  for fail-closed tier-gating. Omit to keep folders always-on (default). */
   readonly toggleable?: FoldersToggleable;
+  /** Row-level ownership on the folder-assignment rows themselves — orthogonal
+   *  to `access`, which only gates whether a caller may dispatch set/clear/list
+   *  at all. Not needed to keep a caller from reading assignments on host
+   *  entities they can't see: that gate is default-on since fw#2766 and derives
+   *  from the entity's `parentRef`. Use `ownership.read` for an ADDITIONAL row
+   *  rule on the assignment row itself; it is AND-ed with the host-visibility
+   *  gate. Applies only to `folder-assignment`; the `folder` catalog stays
+   *  tenant-wide by design.
+   *
+   *  `ownership.write` is separate and does NOT affect list/read. It's consulted
+   *  by the framework's generic delete/forget/restore paths. A `from()` rule
+   *  there also gates GDPR erasure (`forget`): if the rule's role map doesn't
+   *  cover whatever role the erasure/retention pipeline runs as, `forget` denies
+   *  instead of crypto-shredding — a silent Art.17 failure, not a thrown error.
+   *  Make sure any `ownership.write` you set covers that role, or leave it unset. */
+  readonly ownership?: EntityDefinition["access"];
+  /** Allowlist narrowing which registered entities may be filed into a folder.
+   *  Not what turns host-checking on — set/clear and the assignment list always
+   *  verify that entityType names a registered entity whose row the caller can
+   *  see. Setting it narrows further, and shrinks the read gate's SQL, which
+   *  otherwise considers every registered entity as a candidate host. */
+  readonly parents?: readonly string[];
 };
 
 function resolveAccess(opts: FoldersFeatureOptions): AccessRule {
@@ -130,9 +157,36 @@ function resolveAccess(opts: FoldersFeatureOptions): AccessRule {
 // Options wrapper. Without options returns the module-level singleton (no
 // rebuild). access/roles/toggleable build a fresh feature-definition.
 export function createFoldersFeature(opts: FoldersFeatureOptions = {}): typeof foldersFeature {
-  if (opts.access === undefined && opts.roles === undefined && opts.toggleable === undefined) {
+  if (
+    opts.access === undefined &&
+    opts.roles === undefined &&
+    opts.toggleable === undefined &&
+    opts.ownership === undefined &&
+    opts.parents === undefined
+  ) {
     return foldersFeature;
   }
+  if (hasWhereRule(opts.ownership?.write)) {
+    throw new Error(
+      "createFoldersFeature({ ownership }): ownership.write must not contain a " +
+        '`{ kind: "where" }` rule — where-rules are evaluated only at the SQL ' +
+        "layer (the read path, via buildOwnershipClause). Write paths that " +
+        "consult access.write (userCanCreateFieldRow/userCanWriteFieldRow) can't " +
+        "evaluate them, so such a rule can only ever deny — boot validation " +
+        "rejects it too (fw#2626). Use a `from()` rule for ownership.write, or " +
+        "leave it unset.",
+    );
+  }
+  if (opts.parents !== undefined && opts.parents.length === 0) {
+    throw new Error(
+      "createFoldersFeature({ parents }): parents must not be an empty array — " +
+        "an empty allowlist rejects every set-folder call and hides every " +
+        "assignment row. Omit `parents` to keep every registered entity " +
+        "admissible as a host instead.",
+    );
+  }
   const access = resolveAccess(opts);
-  return defineFeature(FOLDERS_FEATURE_NAME, (r) => registerFolders(r, access, opts.toggleable));
+  return defineFeature(FOLDERS_FEATURE_NAME, (r) =>
+    registerFolders(r, access, opts.toggleable, opts.ownership, opts.parents),
+  );
 }

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

@@ -1,6 +1,6 @@
 import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import { parentRowIsVisible } from "../../shared";
+import { joinRowParentIsVisible } from "../../shared";
 import { folderAssignmentAggregateId } from "../aggregate-id";
 import { DEFAULT_FOLDER_ACCESS } from "../constants";
 import { folderAssignmentExecutor } from "../executor";
@@ -31,10 +31,10 @@ export function createClearFolderHandler(
       // an invisible parent apart from a missing assignment or an unknown folder —
       // every path answers with the same NotFoundError.
       if (
-        !(await parentRowIsVisible(
+        !(await joinRowParentIsVisible(
           ctx.registry,
-          payload.entityType,
-          payload.entityId,
+          "folder-assignment",
+          payload,
           event.user,
           ctx.db,
         ))

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

@@ -1,6 +1,6 @@
 import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import { parentRowIsVisible } from "../../shared";
+import { joinRowParentIsVisible } from "../../shared";
 import { folderAssignmentAggregateId } from "../aggregate-id";
 import { DEFAULT_FOLDER_ACCESS } from "../constants";
 import { folderAssignmentExecutor, folderExecutor } from "../executor";
@@ -47,10 +47,10 @@ export function createSetFolderHandler(
       // an invisible parent apart from a missing assignment or an unknown folder —
       // every path answers with the same NotFoundError.
       if (
-        !(await parentRowIsVisible(
+        !(await joinRowParentIsVisible(
           ctx.registry,
-          payload.entityType,
-          payload.entityId,
+          "folder-assignment",
+          payload,
           event.user,
           ctx.db,
         ))

package/src/ledger/__tests__/ledger.integration.test.ts

@@ -64,7 +64,12 @@ async function createAccount(name: string, type: AccountType, user = admin): Pro
 
 async function createTransaction(
   lines: readonly Posting[],
-  opts: { date?: string; description?: string } = {},
+  opts: {
+    date?: string;
+    description?: string;
+    subjectType?: string;
+    subjectId?: string;
+  } = {},
   user = admin,
 ): Promise<{ id: string }> {
   return stack.http.writeOk<{ id: string }>(
@@ -73,15 +78,20 @@ async function createTransaction(
       date: opts.date ?? "2026-01-15",
       description: opts.description ?? "Test entry",
       lines,
+      ...(opts.subjectType !== undefined && { subjectType: opts.subjectType }),
+      ...(opts.subjectId !== undefined && { subjectId: opts.subjectId }),
     },
     user,
   );
 }
 
-async function listTransactions(user = admin): Promise<Array<Record<string, unknown>>> {
+async function listTransactions(
+  user = admin,
+  query: Record<string, unknown> = {},
+): Promise<Array<Record<string, unknown>>> {
   const res = await stack.http.queryOk<{ rows: Array<Record<string, unknown>> }>(
     LedgerQueries.transactionList,
-    {},
+    query,
     user,
   );
   return res.rows;
@@ -350,7 +360,13 @@ describe("ledger integration — confirm-schedule-period (recurring)", () => {
   async function createSchedule(
     debitAccountId: string,
     creditAccountId: string,
-    over: { amount?: number; description?: string; startDate?: string } = {},
+    over: {
+      amount?: number;
+      description?: string;
+      startDate?: string;
+      subjectType?: string;
+      subjectId?: string;
+    } = {},
   ): Promise<string> {
     const s = await stack.http.writeOk<{ id: string }>(
       LedgerHandlers.createSchedule,
@@ -361,6 +377,8 @@ describe("ledger integration — confirm-schedule-period (recurring)", () => {
         amount: over.amount ?? 50000,
         debitAccountId,
         creditAccountId,
+        ...(over.subjectType !== undefined && { subjectType: over.subjectType }),
+        ...(over.subjectId !== undefined && { subjectId: over.subjectId }),
       },
       admin,
     );
@@ -457,4 +475,93 @@ describe("ledger integration — confirm-schedule-period (recurring)", () => {
     // Books net to zero (original cancels Storno) plus the fresh 48000 confirmation.
     expect(trialBalance(rows)).toBe(0);
   });
+
+  test("confirming a period on a schedule with a subject stamps the same subject onto the transaction", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+    const scheduleId = await createSchedule(bank, rent, {
+      subjectType: "lease",
+      subjectId: "lease-1",
+    });
+
+    await confirm(scheduleId, "2026-01");
+
+    const rows = await listTransactions();
+    expect(rows[0]?.["subjectType"]).toBe("lease");
+    expect(rows[0]?.["subjectId"]).toBe("lease-1");
+  });
+
+  test("confirming a period on a schedule without a subject leaves the transaction without one", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+    const scheduleId = await createSchedule(bank, rent);
+
+    await confirm(scheduleId, "2026-01");
+
+    const rows = await listTransactions();
+    expect(rows[0]?.["subjectType"]).toBeNull();
+    expect(rows[0]?.["subjectId"]).toBeNull();
+  });
+});
+
+describe("ledger integration — subject dimension (filterable business-object reference)", () => {
+  test("a booking with subjectType/subjectId round-trips and is findable via an eq filter", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+
+    const tx = await createTransaction(
+      [
+        { accountId: bank, amount: 100000 },
+        { accountId: rent, amount: -100000 },
+      ],
+      { description: "Miete WE1", subjectType: "lease", subjectId: "lease-1" },
+    );
+    await createTransaction(
+      [
+        { accountId: bank, amount: 60000 },
+        { accountId: rent, amount: -60000 },
+      ],
+      { description: "Miete WE2", subjectType: "lease", subjectId: "lease-2" },
+    );
+
+    const rows = await listTransactions(admin, {
+      filter: { field: "subjectId", op: "eq", value: "lease-1" },
+    });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["id"]).toBe(tx.id);
+    expect(rows[0]?.["subjectType"]).toBe("lease");
+    expect(rows[0]?.["subjectId"]).toBe("lease-1");
+  });
+
+  test("an in-filter over multiple subjectId values returns exactly the matching bookings", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+
+    await createTransaction(
+      [
+        { accountId: bank, amount: 10000 },
+        { accountId: rent, amount: -10000 },
+      ],
+      { subjectType: "lease", subjectId: "lease-1" },
+    );
+    await createTransaction(
+      [
+        { accountId: bank, amount: 20000 },
+        { accountId: rent, amount: -20000 },
+      ],
+      { subjectType: "lease", subjectId: "lease-2" },
+    );
+    await createTransaction(
+      [
+        { accountId: bank, amount: 30000 },
+        { accountId: rent, amount: -30000 },
+      ],
+      { subjectType: "lease", subjectId: "lease-3" },
+    );
+
+    const rows = await listTransactions(admin, {
+      filters: [{ field: "subjectId", op: "in", value: ["lease-1", "lease-3"] }],
+    });
+    expect(rows.map((r) => r["subjectId"]).sort()).toEqual(["lease-1", "lease-3"]);
+  });
 });

package/src/ledger/entity.ts

@@ -78,7 +78,22 @@ export const transactionEntity = createEntity({
       },
       { required: true },
     ),
+    // Optional business-object reference (e.g. a lease contract) so entries can
+    // be filtered by what they're about, not just grepped out of `reference`.
+    subjectType: createTextField({
+      maxLength: 64,
+      personal: false,
+      reason: "technical_reference",
+      filterable: true,
+    }),
+    subjectId: createTextField({
+      maxLength: 128,
+      personal: false,
+      reason: "technical_reference",
+      filterable: true,
+    }),
   },
+  indexes: [{ columns: ["tenantId", "subjectType", "subjectId"] }],
 });
 
 // schedule — a recurring booking template (Dauerauftrag): "book `amount` from
@@ -116,5 +131,20 @@ export const scheduleEntity = createEntity({
       personal: false,
       reason: "technical_reference",
     }),
+    // Confirmed periods inherit this from the schedule (see
+    // confirm-schedule-period.write.ts) rather than repeating it per period.
+    subjectType: createTextField({
+      maxLength: 64,
+      personal: false,
+      reason: "technical_reference",
+      filterable: true,
+    }),
+    subjectId: createTextField({
+      maxLength: 128,
+      personal: false,
+      reason: "technical_reference",
+      filterable: true,
+    }),
   },
+  indexes: [{ columns: ["tenantId", "subjectType", "subjectId"] }],
 });

package/src/ledger/handlers/confirm-schedule-period.write.ts

@@ -96,6 +96,11 @@ export function createConfirmSchedulePeriodHandler(
       }
 
       const amount = payload.amount ?? Number(schedule["amount"]);
+      // The subject is a property of the schedule, not the confirm call — a
+      // period without one stays without one, no backfill/error.
+      const subjectType =
+        typeof schedule["subjectType"] === "string" ? schedule["subjectType"] : null;
+      const subjectId = typeof schedule["subjectId"] === "string" ? schedule["subjectId"] : null;
       const created = await transactionExecutor.create(
         {
           id: generateId(),
@@ -107,6 +112,8 @@ export function createConfirmSchedulePeriodHandler(
             { accountId: debitAccountId, amount },
             { accountId: creditAccountId, amount: -amount },
           ],
+          subjectType,
+          subjectId,
         },
         event.user,
         ctx.db,

package/src/ledger/handlers/create-transaction.write.ts

@@ -35,6 +35,8 @@ export function createCreateTransactionHandler(
           reference: payload.reference ?? null,
           status: payload.status ?? "posted",
           lines: payload.lines,
+          subjectType: payload.subjectType ?? null,
+          subjectId: payload.subjectId ?? null,
         },
         event.user,
         ctx.db,

package/src/ledger/schemas.ts

@@ -27,6 +27,9 @@ export const createTransactionPayloadSchema = z
     // the Soll/recurring work — Phase 0 only ever creates posted entries.
     status: z.enum(TRANSACTION_STATUS).optional(),
     lines: z.array(postingSchema).min(2),
+    // Business-object reference (e.g. a lease contract) this entry is about.
+    subjectType: z.string().max(64).optional(),
+    subjectId: z.string().max(128).optional(),
   })
   .refine((p) => sumIsZero(p.lines), {
     message: "Transaction must balance: Σ of posting amounts must equal 0",

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

@@ -34,7 +34,7 @@ import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testin
 import { userEntity, userTable } from "../../user/schema/user";
 import { seedUser } from "../../user/seeding";
 import { NotesHistoryHandlers, NotesHistoryQueries } from "../constants";
-import { noteEntryEntity } from "../entity";
+import { noteEntryEntity, noteMentionEntity } from "../entity";
 import { createNotesHistoryFeature } from "../feature";
 
 const notesHistoryFeature = createNotesHistoryFeature();
@@ -66,6 +66,7 @@ function memberUser(userId: string): SessionUser {
 beforeAll(async () => {
   stack = await setupTestStack({ features: [notesHistoryFeature, contactFixtureFeature] });
   await unsafeCreateEntityTable(stack.db, noteEntryEntity);
+  await unsafeCreateEntityTable(stack.db, noteMentionEntity);
   await unsafeCreateEntityTable(stack.db, userEntity);
   await unsafeCreateEntityTable(stack.db, contactEntity);
   await asRawClient(stack.db).unsafe(