@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/metrics/validate.ts

@@ -0,0 +1,73 @@
+import { extractTableInfo, isTimestamptzType } from "@cosmicdrift/kumiko-framework/bun-db";
+import { METRIC_RANGES } from "./constants.js";
+import type { MetricDefinition } from "./types.js";
+
+const KEBAB_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const TENANT_ID_FIELD = "tenantId";
+
+export function metricHasTenantColumn(metric: MetricDefinition): boolean {
+  return extractTableInfo(metric.source).hasColumn(TENANT_ID_FIELD);
+}
+
+export function validateMetrics(metrics: readonly MetricDefinition[]): void {
+  const seen = new Set<string>();
+  for (const metric of metrics) {
+    if (seen.has(metric.id)) {
+      throw new Error(`metrics: duplicate metric id "${metric.id}"`);
+    }
+    seen.add(metric.id);
+    validateMetric(metric);
+  }
+}
+
+type Fail = (reason: string) => never;
+type TableInfo = ReturnType<typeof extractTableInfo>;
+
+function validateMetric(metric: MetricDefinition): void {
+  const fail: Fail = (reason) => {
+    throw new Error(`metrics: metric "${metric.id}" ${reason}`);
+  };
+  if (!KEBAB_ID.test(metric.id)) fail("has an id that is not kebab-case");
+  if (metric.scopes.length === 0) fail("declares no scopes");
+
+  const info = extractTableInfo(metric.source);
+  validateColumns(metric, info, fail);
+  validateTimeSettings(metric, info, fail);
+  validateShape(metric, fail);
+  if (metric.scopes.includes("tenant") && !metricHasTenantColumn(metric)) {
+    fail(`has scope "tenant" but ${info.name} has no tenant_id column`);
+  }
+}
+
+function validateColumns(metric: MetricDefinition, info: TableInfo, fail: Fail): void {
+  const requireColumn = (field: string, role: string): void => {
+    if (!info.hasColumn(field)) fail(`${role} "${field}" is not a column of ${info.name}`);
+  };
+  if (metric.measure.fn !== "count") requireColumn(metric.measure.field, "measure field");
+  for (const field of Object.keys(metric.where ?? {})) requireColumn(field, "where field");
+  if (metric.groupBy !== undefined) requireColumn(metric.groupBy, "groupBy field");
+  if (metric.stackBy !== undefined) requireColumn(metric.stackBy, "stackBy field");
+  if (metric.timeField !== undefined) requireColumn(metric.timeField, "timeField");
+}
+
+function validateTimeSettings(metric: MetricDefinition, info: TableInfo, fail: Fail): void {
+  const { timeField } = metric;
+  if (timeField === undefined) {
+    if (metric.bucket !== undefined) fail("sets bucket without timeField");
+    if (metric.window !== undefined) fail("sets window without timeField");
+  } else {
+    if (!isTimestamptzType(info.pgTypeOf(info.columnOf(timeField)))) {
+      fail(`timeField "${timeField}" is not a timestamptz column`);
+    }
+    if (metric.window !== undefined && !METRIC_RANGES.includes(metric.window)) {
+      fail(`has an unknown window "${metric.window}"`);
+    }
+  }
+}
+
+function validateShape(metric: MetricDefinition, fail: Fail): void {
+  if (metric.stackBy !== undefined) {
+    if (metric.groupBy === undefined) fail("sets stackBy without groupBy");
+    if (metric.bucket !== undefined) fail("combines stackBy with bucket");
+  }
+}

package/packages/bundled-features/src/metrics/window.ts

@@ -0,0 +1,89 @@
+import type { AggregateTimeBucket } from "@cosmicdrift/kumiko-types/aggregate-types";
+import { Temporal } from "temporal-polyfill";
+import type { MetricRange } from "./constants.js";
+import type { MetricDefinition } from "./types.js";
+
+export type MetricWindow = {
+  readonly start: Temporal.Instant;
+  readonly end: Temporal.Instant;
+  readonly previousStart: Temporal.Instant;
+};
+
+const RANGE_HOURS: Readonly<Record<MetricRange, number>> = {
+  "24h": 24,
+  "7d": 7 * 24,
+  "14d": 14 * 24,
+  "30d": 30 * 24,
+};
+
+// The 24h range counts as one day when bucketing by day.
+const RANGE_DAYS: Readonly<Record<MetricRange, number>> = {
+  "24h": 1,
+  "7d": 7,
+  "14d": 14,
+  "30d": 30,
+};
+
+// Offset strings ("+01:00") pass Intl/Temporal as ISO offsets but Postgres
+// date_trunc reads them as POSIX zones with the opposite sign, so only named
+// zones are accepted.
+export function isValidTimeZone(timeZone: string): boolean {
+  if (/^[+-]/.test(timeZone)) return false;
+  try {
+    new Intl.DateTimeFormat(undefined, { timeZone });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveBucket(
+  metric: MetricDefinition,
+  range: MetricRange,
+): AggregateTimeBucket | undefined {
+  if (metric.bucket === undefined) return undefined;
+  if (metric.bucket === "auto") return range === "24h" ? "hour" : "day";
+  return metric.bucket;
+}
+
+export function computeWindow(
+  range: MetricRange,
+  bucket: AggregateTimeBucket | undefined,
+  timeZone: string,
+  now: Temporal.Instant,
+): MetricWindow {
+  const zonedNow = now.toZonedDateTimeISO(timeZone);
+  let start: Temporal.Instant;
+  if (bucket === "hour") {
+    const hourStart = zonedNow.round({ smallestUnit: "hour", roundingMode: "floor" });
+    start = hourStart.subtract({ hours: RANGE_HOURS[range] - 1 }).toInstant();
+  } else if (bucket === "day") {
+    start = zonedNow
+      .startOfDay()
+      .subtract({ days: RANGE_DAYS[range] - 1 })
+      .startOfDay()
+      .toInstant();
+  } else {
+    start = now.subtract({ hours: RANGE_HOURS[range] });
+  }
+  const spanMs = now.epochMilliseconds - start.epochMilliseconds;
+  const previousStart = Temporal.Instant.fromEpochMilliseconds(start.epochMilliseconds - spanMs);
+  return { start, end: now, previousStart };
+}
+
+// Every bucket start in [window.start, window.end], in the display zone —
+// SQL only returns buckets that have rows, the chart needs the gaps too.
+export function bucketStartsMs(
+  window: MetricWindow,
+  bucket: AggregateTimeBucket,
+  timeZone: string,
+): readonly number[] {
+  const starts: number[] = [];
+  const step = bucket === "hour" ? { hours: 1 } : { days: 1 };
+  let cursor = window.start.toZonedDateTimeISO(timeZone);
+  while (cursor.epochMilliseconds <= window.end.epochMilliseconds) {
+    starts.push(cursor.epochMilliseconds);
+    cursor = bucket === "day" ? cursor.add(step).startOfDay() : cursor.add(step);
+  }
+  return starts;
+}

package/packages/bundled-features/src/notes-history/changes.json

@@ -0,0 +1,30 @@
+[
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "add-note rejects mentions of non-members; mention export lists mentioning notes",
+    "detail": "notes-history: `add-note` now rejects `mentions` of users who are not members of the current tenant, because their forget run only visits tenants they belong to and would never reach such a note. The notes-history user-data export hook now lists the notes that mention the exporting user.",
+    "migration": "No action needed unless a client mentions user ids that are not members of the tenant; those writes now fail validation."
+  },
+  {
+    "version": "0.308.0",
+    "type": "breaking",
+    "title": "NotesSection no longer wraps its own \"new note\" / \"history\" blocks in a Card (fw#3234)",
+    "detail": "As an extension section (its documented usage: `component: { react: { __component: NOTES_SECTION_EXTENSION_NAME } }`), NotesSection was already mounted inside the host's own section frame — its two internal Cards doubled the border/padding there. Both blocks now use a plain container with a `Heading variant=\"section\"` sub-header instead.",
+    "migration": "A standalone `<NotesSection entityName={...} entityId={id} />` mount (outside a screen-schema extension section) now renders both blocks without their own card chrome — wrap it in a `Section`/`Card` if the standalone mount needs one."
+  },
+  {
+    "version": "0.244.0",
+    "type": "improvement",
+    "title": "add-note now always verifies entityType/entityId against the parent entity's own read path",
+    "detail": "Before this change, add-note took entityType/entityId straight from the client with no check — any dispatch-eligible tenant user could attach a note to any parent object, including one they couldn't otherwise see. add-note now unconditionally verifies that entityType names a registered entity and that the row is visible to the caller through that entity's own read path (tenant scope plus its `access.read` ownership) before accepting the write; entries that fail either check are rejected with a not_found response. createNotesHistoryFeature also accepts a `parents` option — an allowlist further narrowing which registered entities may be a note's parent — but this option is additive-only; the parent-visibility check itself is not gated behind it.",
+    "migration": "entityType must now name an entity registered in the same app (via r.entity(...) or a bundled feature), and the caller must be able to see the target row through that entity's own read path. Any consumer that called add-note with an entityType that is NOT a registered entity name, or with an entityId the caller could not otherwise read, will now get a not_found error instead of a successful write — register the parent entity (and, if it needs row-level ownership, its `access.read` rule) before upgrading."
+  },
+  {
+    "version": "0.215.3",
+    "type": "improvement",
+    "title": "note-entry gains authorName, stamped at write time",
+    "detail": "The entry display previously had no readable author — only the internal authorId (UUID). note-entry now carries an `authorName` field (personal: { of: \"authorId\" }, same crypto-shredding subject as `body`), stamped once at add-note write time from the writer's own read_users row (self-lookup by id, decrypted displayName) so the append-only history keeps the name as it was when the note was written, not whatever the account is called later. A failed lookup, a missing displayName, and pre-field/shredded rows all read `authorName: null` — the UI falls back to a translated placeholder, never the raw id; the write itself never fails over a missing name.",
+    "migration": "Run `kumiko-schema generate` and apply — the migration adds `read_note_entries.authorName`. No backfill: existing rows read null and show the placeholder, same as before this change from the user's point of view."
+  }
+]

package/packages/bundled-features/src/notes-history/constants.ts

@@ -0,0 +1,34 @@
+// @runtime client
+// notes-history bundle constants — feature-name + qualified handler/query names.
+//
+// Spec: kumiko-platform/docs/plans/notes-history-bundle.md
+
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+
+export const NOTES_HISTORY_FEATURE_NAME = "notes-history";
+
+// Registry name for the drop-in <NotesSection> component. Apps reference it
+// in a screen schema via `component: { react: { __component: NOTES_SECTION_EXTENSION_NAME } }`
+// after mounting notesHistoryClient(); also importable directly from
+// `@cosmicdrift/kumiko-bundled-features/notes-history/web` for standalone use.
+export const NOTES_SECTION_EXTENSION_NAME = "NotesSection";
+
+// Qualified handler/query names (QN format: scope:type:name). Clients
+// reference the object instead of magic strings.
+export const NotesHistoryHandlers = {
+  addNote: "notes-history:write:add-note",
+} as const;
+
+export const NotesHistoryQueries = {
+  noteList: "notes-history:query:note-entry:list",
+} as const;
+
+// Default RBAC: any tenant member may read and write notes on entities they
+// can already see — same low-sensitivity-collaboration-tool default as tags.
+// Apps with their own role vocabulary override via
+// createNotesHistoryFeature({ roles }) / ({ access }).
+export const DEFAULT_NOTES_HISTORY_ROLES = ["TenantAdmin", "TenantMember"] as const;
+
+export const DEFAULT_NOTES_HISTORY_ACCESS: AccessRule = {
+  roles: DEFAULT_NOTES_HISTORY_ROLES,
+};

package/packages/bundled-features/src/notes-history/entity.ts

@@ -0,0 +1,128 @@
+import {
+  createEntity,
+  createLongTextField,
+  createTextField,
+  type EntityDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// note-entry — host-agnostic, append-only note attached to ANY entity via
+// (entityType, entityId), same join-row pattern as tags/tag-assignment: no
+// column on the host entity, cross-entity reads compose in the read-layer by
+// filtering on entityId. Unlike tags there is no deterministic aggregate-id —
+// an entity can carry many notes, so every create() is a fresh random-id
+// stream (no idempotency requirement, no restore/version_conflict handling).
+//
+// Strictly append-only by design: no update/delete write-handler is
+// registered (see feature.ts). A correction is a new entry, not an edit —
+// that is the whole point of a note *history* instead of the single
+// overwritable textarea this bundle replaces (solon#13).
+//
+// `body` is about the HOST entity (entityType/entityId), not the author — the
+// author is never the data subject of a note's content, so it is deliberately
+// NOT `personal: { of: "authorId" }`. That axis would crypto-shred every
+// note's content the moment its author's data-rights key is destroyed (an
+// employee leaving triggers a forget), garbling unrelated business notes
+// about customers/projects/etc. — data loss, not privacy.
+//
+// `body` is instead `personal: { of: "id" }` (Row-Subject, fw#2596/#2786):
+// the note's OWN row is its content's subject, so `body` is encrypted under a
+// per-note key that nothing else shares. That key gets erased only when
+// `note-mention` (below) names this note as reached by a forgotten subject
+// (see `notes-history-user-data/hooks.ts`) — a note with no mention on the
+// forgotten subject is untouched. GDPR erasure of the AUTHOR still separately
+// shreds `authorName` (`personal: { of: "authorId" }`, the name as stamped at
+// write time); the two erasures are independent.
+//
+// Known gap (fw#2596, not fixed by this entity): prose that names a third
+// party without a structured @-mention is not tracked — regex/NLP over
+// free text is unreliable. The operator's manual `forget-subject` path
+// covers what this structured trigger misses.
+export function createNoteEntryEntity(
+  access?: EntityDefinition["access"],
+  parents?: readonly string[],
+) {
+  return createEntity({
+    table: "read_note_entries",
+    description:
+      "One note attached to a host entity by entityType and entityId, holding the note body plus the id and the display name of the author as it stood when the note was written. Rows are append-only: a correction is a further note, never an edit of this one.",
+    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: {
+      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",
+      }),
+      // Never client-supplied — stamped by the deriveAuthorId preSave hook from
+      // ctx.user.id (see feature.ts), so a note can't be authored as someone
+      // else. subjectRef feeds the GDPR-hook-coverage boot guard (it's a plain
+      // FK into `user`, not content of its own).
+      authorId: createTextField({
+        personal: "ref",
+      }),
+      // Stamped once at write time, never re-resolved later — the history
+      // needs the name as it was then, not whatever the account is called now.
+      authorName: createTextField({
+        maxLength: 200,
+        personal: { of: "authorId" },
+        find: "none",
+      }),
+      body: createLongTextField({
+        required: true,
+        maxLength: 20_000,
+        // Row-Subject (fw#2596/#2786): the note itself is the subject, so its
+        // key is erased per-note via `note-mention` lookups, not tied to any
+        // user's own forget.
+        personal: { of: "id" },
+        find: "none",
+      }),
+    },
+  });
+}
+
+export const noteEntryEntity = createNoteEntryEntity();
+
+// note-mention — join row recording that a note names a subject via a
+// structured @-mention in the editor (never parsed out of `body` text — see
+// the header comment above). One row per (note, mentioned subject); a note
+// with several mentions gets several rows.
+//
+// `subjectId` is the plain FK to the mentioned user's id — `personal: "ref"`
+// marks it as a subject reference for the GDPR-hook-coverage boot guard
+// (same role as `authorId` on note-entry above), not itself encrypted.
+// `notes-history-user-data/hooks.ts` looks this table up by `subjectId` when
+// a user is forgotten, to find every note whose row-subject key must be
+// erased; see that file for the cascade and the retention-consult step it
+// runs first.
+export function createNoteMentionEntity() {
+  return createEntity({
+    table: "read_note_mentions",
+    description:
+      "One row recording that a note names a subject via a structured @-mention, keyed by noteId and the mentioned subject's id.",
+    fields: {
+      noteId: createTextField({
+        required: true,
+        maxLength: 64,
+        personal: false,
+        reason: "technical_reference",
+      }),
+      subjectId: createTextField({ required: true, maxLength: 64, personal: "ref" }),
+    },
+  });
+}
+
+export const noteMentionEntity = createNoteMentionEntity();

package/packages/bundled-features/src/notes-history/executor.ts

@@ -0,0 +1,22 @@
+import { createEntityExecutor, type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createNoteEntryEntity, noteEntryEntity, noteMentionEntity } from "./entity.js";
+
+export const { executor: noteEntryExecutor, table: noteEntryTable } = createEntityExecutor(
+  "note-entry",
+  noteEntryEntity,
+);
+
+// Carries only `ownership.write`: the executor enforces entity.access.write on
+// create, while read ownership is applied by the list handler.
+export function createNoteEntryExecutor(
+  ownership: EntityDefinition["access"] | undefined,
+): typeof noteEntryExecutor {
+  if (ownership?.write === undefined) return noteEntryExecutor;
+  return createEntityExecutor("note-entry", createNoteEntryEntity({ write: ownership.write }))
+    .executor;
+}
+
+export const { executor: noteMentionExecutor, table: noteMentionTable } = createEntityExecutor(
+  "note-mention",
+  noteMentionEntity,
+);

package/packages/bundled-features/src/notes-history/feature.ts

@@ -0,0 +1,150 @@
+// notes-history — generic, host-agnostic, append-only note history for ANY
+// entity. Replaces a single overwritable textarea (e.g. solon's
+// contact.notes) with multiple timestamped, authored entries — who wrote
+// what, when, is reconstructable instead of lost on the next overwrite.
+//
+// Event-sourced, not relational, same pattern as tags/tag-assignment: the
+// feature owns one entity, `note-entry` (read_note_entries), keyed by
+// (entityType, entityId) — no column on the host entity, no JOIN. Unlike
+// tags there is no deterministic aggregate-id: many notes may exist per
+// entity, so every create() is an ordinary random-id stream.
+//
+// Only create + list are registered — no update, no delete. A correction is
+// a new entry, not an edit; see entity.ts for why that still satisfies GDPR
+// erasure without a delete path.
+
+import {
+  type AccessRule,
+  defineEntityListHandler,
+  defineFeature,
+  type EntityDefinition,
+  type FeatureRegistrar,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { hasWhereRule } from "../shared/index.js";
+import { DEFAULT_NOTES_HISTORY_ACCESS, NOTES_HISTORY_FEATURE_NAME } from "./constants.js";
+import { createNoteEntryEntity, noteMentionEntity } from "./entity.js";
+import { createNoteEntryExecutor } from "./executor.js";
+import { createAddNoteHandler } from "./handlers/add-note.write.js";
+import { NOTES_HISTORY_FEATURE_I18N } from "./i18n.js";
+
+function registerNotesHistory(
+  r: FeatureRegistrar<typeof NOTES_HISTORY_FEATURE_NAME>,
+  access: AccessRule,
+  ownership: EntityDefinition["access"] | undefined,
+  parents: readonly string[] | undefined,
+): void {
+  r.describe(
+    "Generic, host-agnostic, append-only note history for any entity. Owns one event-sourced entity, `note-entry` (`read_note_entries`), keyed by (entityType, entityId) — so attaching notes adds NO column to the host entity and needs no relational pivot or JOIN. Provides a `create` write-handler (author stamped server-side from the caller, never client-supplied) and a `list` query filterable on entityId. Deliberately append-only: no update or delete handler is registered — a correction is a new entry, not an edit, so who-said-what-when stays reconstructable. Every path uses one access rule — adopt the host's model with createNotesHistoryFeature({ access: { openToAll: { reason } } }) or pin roles with createNotesHistoryFeature({ roles }).",
+  );
+  r.uiHints({
+    displayLabel: "Notes",
+    category: "data",
+    recommended: false,
+  });
+
+  const entity = createNoteEntryEntity(ownership, parents);
+  r.entity("note-entry", entity);
+  // No write/query handler of its own — populated only as a side effect of
+  // add-note (see handlers/add-note.write.ts), looked up by
+  // notes-history-user-data's forget cascade. Registering the entity (not
+  // just building it inline in the handler) is what makes it visible to the
+  // registry-wide GDPR boot guards and to executor.ts's table/projection setup.
+  r.entity("note-mention", noteMentionEntity);
+
+  r.writeHandler(createAddNoteHandler(access, createNoteEntryExecutor(ownership)));
+  r.queryHandler(
+    defineEntityListHandler("note-entry", entity, {
+      access,
+      description:
+        "Lists note-history entries of the caller's tenant with their text, author and timestamp; filter on entityId to read the full note trail of one record.",
+    }),
+  );
+
+  r.translations({ keys: NOTES_HISTORY_FEATURE_I18N });
+}
+
+export const notesHistoryFeature = defineFeature(NOTES_HISTORY_FEATURE_NAME, (r) =>
+  registerNotesHistory(r, DEFAULT_NOTES_HISTORY_ACCESS, undefined, undefined),
+);
+
+export type NotesHistoryFeatureOptions = {
+  /** Access rule for the create/list paths. Default { roles: ["TenantAdmin","TenantMember"] }.
+   *  Adopt the host's model — e.g. { openToAll: { reason: "..." } } when the host lets any
+   *  authenticated tenant user write (like the rest of its handlers), or
+   *  { roles: ["Admin"] } for a custom role vocabulary. Takes precedence over `roles`. */
+  readonly access?: AccessRule;
+  /** Shorthand for { access: { roles } }. Ignored when `access` is set. */
+  readonly roles?: readonly string[];
+  /** Row-level ownership on the note-entry rows themselves — orthogonal to
+   *  `access`, which only gates whether a caller may dispatch create/list at
+   *  all. `ownership.read` is no longer what keeps a caller from reading notes
+   *  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 note row itself (e.g. author-only visibility);
+   *  it is AND-ed with the host-visibility gate, never a replacement for it.
+   *
+   *  `ownership.write` is separate and does NOT affect list/read. It's
+   *  consulted on add-note (create) and the framework's generic
+   *  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 further narrowing which registered entities may be used as a
+   *  note's parent (entityType). This is NOT what turns parent-checking on —
+   *  both paths always verify that entityType names a registered entity and
+   *  that the row is visible to the caller through that entity's own read
+   *  path (tenant scope plus its `access.read` ownership); an entityType
+   *  that names no registered entity is rejected regardless of this option.
+   *  Setting `parents` narrows further, to a specific set of entity names —
+   *  useful when a host entity is registered but should never be a valid
+   *  note parent. It also shrinks the read gate's SQL, which otherwise has to
+   *  consider every registered entity as a candidate host. */
+  readonly parents?: readonly string[];
+};
+
+function resolveAccess(opts: NotesHistoryFeatureOptions): AccessRule {
+  if (opts.access !== undefined) return opts.access;
+  if (opts.roles !== undefined) return { roles: opts.roles };
+  return DEFAULT_NOTES_HISTORY_ACCESS;
+}
+
+// Options wrapper. Without options returns the module-level singleton (no
+// rebuild). access/roles/ownership build a fresh feature-definition.
+export function createNotesHistoryFeature(
+  opts: NotesHistoryFeatureOptions = {},
+): typeof notesHistoryFeature {
+  if (
+    opts.access === undefined &&
+    opts.roles === undefined &&
+    opts.ownership === undefined &&
+    opts.parents === undefined
+  ) {
+    return notesHistoryFeature;
+  }
+  if (hasWhereRule(opts.ownership?.write)) {
+    throw new Error(
+      "createNotesHistoryFeature({ 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.",
+    );
+  }
+  // A mount that accepts no parents at all can never take a note write —
+  // that's a config mistake, not a valid allowlist. Omit `parents` instead
+  // of passing an empty array.
+  if (opts.parents !== undefined && opts.parents.length === 0) {
+    throw new Error(
+      "createNotesHistoryFeature({ parents }): parents must not be an empty array — " +
+        "an empty allowlist rejects every add-note call. Omit `parents` to allow " +
+        "any registered entity the caller can read as a note parent.",
+    );
+  }
+  return defineFeature(NOTES_HISTORY_FEATURE_NAME, (r) =>
+    registerNotesHistory(r, resolveAccess(opts), opts.ownership, opts.parents),
+  );
+}

package/packages/bundled-features/src/notes-history/handlers/add-note.write.ts

@@ -0,0 +1,118 @@
+import { fetchOne, runInSavepointIfSupported } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { ValidationError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { decryptStoredPii, denyUnlessJoinRowParentVisible } from "../../shared/index.js";
+import { tenantMembershipsTable } from "../../tenant/index.js";
+import { userTable } from "../../user/index.js";
+import { DEFAULT_NOTES_HISTORY_ACCESS } from "../constants.js";
+import { noteEntryExecutor, noteMentionExecutor } from "../executor.js";
+import { type AddNotePayload, addNotePayloadSchema } from "../schemas.js";
+
+const READ_AUTHOR_DISPLAY_NAME_REASON =
+  "reads the author's displayName from the global users table inside a savepoint so a missing user feature cannot poison the note transaction";
+
+// add-note — appends a note-entry to (entityType, entityId). authorId is
+// NEVER read from the payload: it is always the authenticated caller
+// (event.user.id), so a note can't be authored as someone else. No update or
+// delete counterpart is registered — see entity.ts for why append-only is
+// deliberate.
+//
+// entityType/entityId are never trusted client input: entityType must name a
+// registered entity, and the row must be visible to the caller through that
+// entity's own read path (tenant scope plus its `access.read` ownership).
+// Both the field names and the optional `parents` allowlist come from the
+// entity's own `parentRef` declaration, which the read gate reads too —
+// see shared/parent-visibility.ts.
+export function createAddNoteHandler(
+  access: AccessRule = DEFAULT_NOTES_HISTORY_ACCESS,
+  entryExecutor: typeof noteEntryExecutor = noteEntryExecutor,
+): WriteHandlerDef {
+  return {
+    name: "add-note",
+    schema: addNotePayloadSchema,
+    access,
+    description:
+      "Appends a note to one host entity's history, stamping the author from the authenticated caller rather than the payload; use it for every remark and correction alike, because entries can never be edited or removed afterwards.",
+    escapeHatch: {
+      grants: ["unsafeRaw"],
+      reason: READ_AUTHOR_DISPLAY_NAME_REASON,
+    },
+    handler: async (event, ctx) => {
+      const payload = event.payload as AddNotePayload; // @cast-boundary engine-payload
+
+      const denied = await denyUnlessJoinRowParentVisible(
+        ctx.registry,
+        "note-entry",
+        payload,
+        event.user,
+        ctx.db,
+      );
+      if (denied) return denied;
+
+      // A mention of a non-member would leave a note body about that person out of reach of
+      // their forget run, which only visits the tenants they are a member of.
+      const mentionedUserIds = [...new Set(payload.mentions ?? [])];
+      if (mentionedUserIds.length > 0) {
+        const memberRows = await ctx.db.selectMany<{ userId: string }>(tenantMembershipsTable, {
+          userId: { in: mentionedUserIds },
+        });
+        const memberIds = new Set(memberRows.map((row) => row.userId));
+        if (mentionedUserIds.some((userId) => !memberIds.has(userId))) {
+          return writeFailure(
+            new ValidationError({
+              fields: [{ path: "mentions", code: "custom", i18nKey: "errors.validation.custom" }],
+            }),
+          );
+        }
+      }
+
+      let authorName: string | null = null;
+      try {
+        // read_users is tenant-agnostic → ctx.db.unsafeRaw, not the tenant-scoped ctx.db.
+        // Bun.SQL poisons the whole tx after any error inside it, even one that's
+        // caught — so the lookup runs in a savepoint where available, otherwise directly
+        // (pool statements are their own units).
+        authorName = await runInSavepointIfSupported(
+          ctx.db.unsafeRaw(READ_AUTHOR_DISPLAY_NAME_REASON),
+          async (sp) => {
+            const userRow = await fetchOne<{ displayName: string | null }>(sp, userTable, {
+              id: event.user.id,
+            });
+            if (!userRow?.displayName) return null;
+            return decryptStoredPii(userRow.displayName, "displayName", "notes-history:add-note");
+          },
+        );
+      } catch (e) {
+        ctx.log?.warn("notes-history: authorName lookup failed", {
+          error: e,
+          userId: event.user.id,
+        });
+        authorName = null;
+      }
+
+      const { mentions, ...notePayload } = payload;
+      const created = await entryExecutor.create(
+        { ...notePayload, authorId: event.user.id, authorName },
+        event.user,
+        ctx.db,
+      );
+      if (!created.isSuccess) return created;
+
+      // Same tx as the note create above (ctx.db) — a mention-row failure
+      // rolls the note back with it, same as the framework's own nested-write
+      // parent+child pattern (dispatch-write.ts).
+      for (const subjectId of mentionedUserIds) {
+        const mentionResult = await noteMentionExecutor.create(
+          { noteId: created.data.id, subjectId },
+          event.user,
+          ctx.db,
+        );
+        if (!mentionResult.isSuccess) return mentionResult;
+      }
+
+      return created;
+    },
+  };
+}
+
+export const addNoteHandler: WriteHandlerDef = createAddNoteHandler();

package/packages/bundled-features/src/notes-history/i18n.ts

@@ -0,0 +1,3 @@
+type LocalizedString = { readonly en: string };
+
+export const NOTES_HISTORY_FEATURE_I18N: Readonly<Record<string, LocalizedString>> = {};