@cosmicdrift/kumiko-samples 0.353.0 → 0.354.0

package/packages/bundled-features/src/jobs/job-run-logger.ts

@@ -2,8 +2,11 @@ import {
   deleteMany,
   fetchOne,
   insertMany,
+  insertOnConflictDoNothing,
   insertOne,
+  transaction,
   updateMany,
+  upsertOnConflict,
 } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configuredPiiSubjectKms,
@@ -12,12 +15,13 @@ import {
   type LocalKeyKmsAdapter,
   PII_ERASED_SENTINEL,
 } from "@cosmicdrift/kumiko-framework/crypto";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { acquireNamespacedAdvisoryLock, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { type Registry, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import type {
   JobLogEntry,
   JobMeta,
   JobOutcomeMeta,
+  JobQueuedMeta,
   JobRunnerOptions,
 } from "@cosmicdrift/kumiko-framework/jobs";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
@@ -27,6 +31,7 @@ import { runCompletedSchema, runFailedSchema, runStartedSchema } from "./events.
 import { parseJobInstant } from "./job-instant.js";
 import { jobRunLogsTable, jobRunsTable } from "./job-run-table.js";
 import { tenantJobFailuresTable } from "./tenant-job-failure-table.js";
+import { tenantJobRunsTable } from "./tenant-job-run-table.js";
 
 // Matches PgKmsAdapter's default pool size (see tenant/handlers/*.query.ts) —
 // bounds concurrent getOrCreateDek calls so a large log batch doesn't claim
@@ -51,7 +56,7 @@ export type JobRunLoggerOptions = {
 
 export type JobRunLoggerCallbacks = Pick<
   JobRunnerOptions,
-  "onJobStart" | "onJobComplete" | "onJobFailed"
+  "onJobStart" | "onJobComplete" | "onJobFailed" | "onJobQueued" | "onJobDropped"
 >;
 
 // Default cap on the bullJobId → runId cache. A worker that starts jobs
@@ -151,6 +156,10 @@ async function encryptStartedPayload(
   return encryptOrSentinel(kms, triggeredById, payload, "payload");
 }
 
+// pg_advisory_xact_lock namespace (int4): 'tjfl' as ASCII, disjoint from the
+// framework's other fixed advisory-lock keys.
+const TENANT_JOB_FAILURE_LOCK_NAMESPACE = 0x746a666c;
+
 // fw#3079 — which row the tenant-visible failure record lives in: one per
 // (tenant, job, subject), so the next outcome of the same work replaces or
 // clears it. `subject` is null for a job that declares no subjectFields.
@@ -177,14 +186,22 @@ async function recordTenantJobFailure(
   // non-final failure must not show the tenant a failure the next attempt
   // may still resolve.
   if (!where || !messageKey || outcome?.finalAttempt !== true) return;
-  // ponytail: delete-then-insert instead of an upsert — two runs of the same
-  // key finishing at once can leave two rows, and the query returns the
-  // newest. Add a unique index + ON CONFLICT if that ever matters.
-  await deleteMany(db, tenantJobFailuresTable, where);
-  await insertOne(db, tenantJobFailuresTable, {
-    ...where,
-    messageKey,
-    failedAt: Temporal.Now.instant(),
+  // Delete-then-insert under a per-key lock instead of an upsert: the two
+  // partial unique indexes (subject NULL vs. set) are no ON CONFLICT target.
+  // The lock makes the later of two racing final failures replace the earlier
+  // one; the indexes are the backstop against any writer that skips the lock.
+  await transaction(db, async (tx) => {
+    await acquireNamespacedAdvisoryLock(
+      tx,
+      TENANT_JOB_FAILURE_LOCK_NAMESPACE,
+      JSON.stringify([where["tenantId"], where["jobName"], where["subject"]]),
+    );
+    await deleteMany(tx, tenantJobFailuresTable, where);
+    await insertOne(tx, tenantJobFailuresTable, {
+      ...where,
+      messageKey,
+      failedAt: Temporal.Now.instant(),
+    });
   });
 }
 
@@ -199,8 +216,131 @@ async function clearTenantJobFailure(
   await deleteMany(db, tenantJobFailuresTable, where);
 }
 
+// fw#3616 — tenant-visible run state. One row per BullMQ job in
+// store_tenant_job_runs; the writes below only ever touch rows of the same
+// bullJobId, except pruning older finished rows of the same key.
+type TenantRunKey = {
+  readonly tenantId: string;
+  readonly jobName: string;
+  readonly subject: string | null;
+};
+
+function tenantRunKey(
+  jobName: string,
+  tenantId: string,
+  subject: string | null,
+): TenantRunKey | null {
+  // skip: tenant-less run (cron resolves to SYSTEM_TENANT_ID) — no tenant-scoped query could read it
+  if (tenantId === SYSTEM_TENANT_ID) return null;
+  return { tenantId, jobName, subject };
+}
+
+async function recordTenantRunQueued(
+  db: DbConnection,
+  jobName: string,
+  bullJobId: string,
+  meta: JobQueuedMeta,
+): Promise<void> {
+  const key = tenantRunKey(jobName, meta.tenantId, meta.subject);
+  // skip: system-tenant run, no tenant-scoped query reads it
+  if (!key) return;
+  const now = Temporal.Now.instant();
+  // DO NOTHING: a fast worker can report the start before this enqueue hook
+  // returns, and a repeated jobId (debounce, fan-out dedup) is the same job.
+  await insertOnConflictDoNothing(
+    db,
+    tenantJobRunsTable,
+    { ...key, bullJobId, status: "queued", queuedAt: now, updatedAt: now },
+    { conflictKeys: ["bullJobId"] },
+  );
+}
+
+async function recordTenantRunStarted(
+  db: DbConnection,
+  jobName: string,
+  bullJobId: string,
+  meta: JobMeta,
+): Promise<void> {
+  // skip: job did not opt in to tenantVisibleRun
+  if (!meta.tenantVisibleRun) return;
+  const key = tenantRunKey(jobName, meta.tenantVisibleRun.tenantId, meta.tenantVisibleRun.subject);
+  // skip: system-tenant run, no tenant-scoped query reads it
+  if (!key) return;
+  const now = Temporal.Now.instant();
+  await upsertOnConflict(
+    db,
+    tenantJobRunsTable,
+    { ...key, bullJobId, status: "running", startedAt: now, updatedAt: now },
+    {
+      conflictKeys: ["bullJobId"],
+      update: { status: "running", startedAt: now, finishedAt: null, updatedAt: now },
+    },
+  );
+}
+
+async function recordTenantRunOutcome(
+  db: DbConnection,
+  jobName: string,
+  bullJobId: string,
+  outcome: JobOutcomeMeta | undefined,
+  result: "completed" | "failed",
+): Promise<void> {
+  // skip: job did not opt in to tenantVisibleRun
+  if (!outcome?.tenantVisibleRun) return;
+  const key = tenantRunKey(jobName, outcome.tenantId, outcome.tenantVisibleRun.subject);
+  // skip: system-tenant run, no tenant-scoped query reads it
+  if (!key) return;
+  const now = Temporal.Now.instant();
+  // A failed attempt BullMQ will retry goes back to waiting: the tenant keeps
+  // seeing pending work, not a failure the next attempt may still resolve.
+  if (result === "failed" && !outcome.finalAttempt) {
+    await updateMany(
+      db,
+      tenantJobRunsTable,
+      { status: "queued", startedAt: null, finishedAt: null, updatedAt: now },
+      { bullJobId },
+    );
+    // skip: retry pending, the row stays active until the final attempt
+    return;
+  }
+  await upsertOnConflict(
+    db,
+    tenantJobRunsTable,
+    { ...key, bullJobId, status: result, finishedAt: now, updatedAt: now },
+    { conflictKeys: ["bullJobId"], update: { status: result, finishedAt: now, updatedAt: now } },
+  );
+  await deleteMany(db, tenantJobRunsTable, {
+    ...key,
+    status: { in: ["completed", "failed"] },
+    bullJobId: { ne: bullJobId },
+  });
+}
+
+async function dropTenantRunQueued(db: DbConnection, bullJobId: string): Promise<void> {
+  await deleteMany(db, tenantJobRunsTable, { bullJobId, status: "queued" });
+}
+
 const log = createFallbackLogger("job-run-logger");
 
+// The tenant run state is an optional side write: a throw here must not
+// fail the enqueue, skip the run-row write or turn a completed run into a
+// BullMQ retry.
+async function isolateTenantRunWrite(
+  write: () => Promise<void>,
+  jobName: string,
+  bullJobId: string,
+): Promise<void> {
+  try {
+    await write();
+  } catch (e) {
+    log.error("tenant job run state write failed", {
+      jobName,
+      bullJobId,
+      error: e instanceof Error ? e.message : String(e),
+    });
+  }
+}
+
 // The tenant failure record is an optional side write: a throw here must not
 // skip the run-row update or turn a completed run into a BullMQ retry.
 async function isolateTenantFailureWrite(
@@ -289,7 +429,24 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
   }
 
   return {
+    onJobQueued: async (jobName: string, bullJobId: string, meta: JobQueuedMeta) => {
+      await isolateTenantRunWrite(
+        () => recordTenantRunQueued(db, jobName, bullJobId, meta),
+        jobName,
+        bullJobId,
+      );
+    },
+
+    onJobDropped: async (jobName: string, bullJobId: string) => {
+      await isolateTenantRunWrite(() => dropTenantRunQueued(db, bullJobId), jobName, bullJobId);
+    },
+
     onJobStart: async (jobName: string, bullJobId: string, meta: JobMeta) => {
+      await isolateTenantRunWrite(
+        () => recordTenantRunStarted(db, jobName, bullJobId, meta),
+        jobName,
+        bullJobId,
+      );
       const runId = generateId();
       const triggeredById = meta.triggeredById ?? null;
       cachePut(bullJobId, runId, triggeredById);
@@ -336,6 +493,11 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
         jobName,
         bullJobId,
       );
+      await isolateTenantRunWrite(
+        () => recordTenantRunOutcome(db, jobName, bullJobId, outcome, "completed"),
+        jobName,
+        bullJobId,
+      );
       const resolved = await resolveRun(bullJobId);
       // skip: state loss between start + complete (worker restart, cache
       // evicted AND DB has no matching bull_job_id). Rare edge case; we
@@ -400,6 +562,11 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
         jobName,
         bullJobId,
       );
+      await isolateTenantRunWrite(
+        () => recordTenantRunOutcome(db, jobName, bullJobId, outcome, "failed"),
+        jobName,
+        bullJobId,
+      );
       const resolved = await resolveRun(bullJobId);
       // skip: same rare state-loss case as in onJobComplete — drop the
       // failure write rather than forge a run row from scratch.

package/packages/bundled-features/src/jobs/tenant-job-failure-table.ts

@@ -1,11 +1,13 @@
 import { requireEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   type EntityTableMeta,
+  index,
   instant,
   table as pgTable,
   serial,
   sql,
   text,
+  uniqueIndex,
   uuid,
 } from "@cosmicdrift/kumiko-framework/db";
 
@@ -23,14 +25,31 @@ import {
 // canonical JSON of the job's declared subjectFields, or NULL for a job that
 // declares none — stored in clear, so a job must not declare a PII field
 // as its subject.
-export const tenantJobFailuresTable = pgTable("store_tenant_job_failures", {
-  id: serial("id").primaryKey(),
-  tenantId: uuid("tenant_id").notNull(),
-  jobName: text("job_name").notNull(),
-  subject: text("subject"),
-  messageKey: text("message_key").notNull(),
-  failedAt: instant("failed_at").default(sql`now()`).notNull(),
-});
+export const tenantJobFailuresTable = pgTable(
+  "store_tenant_job_failures",
+  {
+    id: serial("id").primaryKey(),
+    tenantId: uuid("tenant_id").notNull(),
+    jobName: text("job_name").notNull(),
+    subject: text("subject"),
+    messageKey: text("message_key").notNull(),
+    failedAt: instant("failed_at").default(sql`now()`).notNull(),
+  },
+  (t) => [
+    // One row per key, also the lookup for the delete before every write;
+    // subject NULL needs its own partial index because NULLs
+    // are distinct in a plain unique index.
+    uniqueIndex("store_tenant_job_failures_tenant_job_subject_uidx")
+      .on(t.tenantId, t.jobName, t.subject)
+      .where(sql`subject IS NOT NULL`),
+    uniqueIndex("store_tenant_job_failures_tenant_job_null_subject_uidx")
+      .on(t.tenantId, t.jobName)
+      .where(sql`subject IS NULL`),
+    // The tenant list sorts by failed_at; retention filters on it alone.
+    index("store_tenant_job_failures_tenant_failed_at_idx").on(t.tenantId, t.failedAt),
+    index("store_tenant_job_failures_failed_at_idx").on(t.failedAt),
+  ],
+);
 
 export const tenantJobFailuresTableMeta: EntityTableMeta = requireEntityTableMeta(
   tenantJobFailuresTable,

package/packages/bundled-features/src/jobs/tenant-job-run-table.ts

@@ -0,0 +1,55 @@
+import { requireEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  type EntityTableMeta,
+  index,
+  instant,
+  table as pgTable,
+  serial,
+  sql,
+  text,
+  uniqueIndex,
+  uuid,
+} from "@cosmicdrift/kumiko-framework/db";
+
+export type TenantJobRunStatus = "queued" | "running" | "completed" | "failed";
+
+// The tenant's own view of a job's run state (fw#3616). Direct-write store
+// like store_job_runs, written by job-run-logger.ts from the runner callbacks.
+//
+// store_job_runs cannot serve the tenant: it anchors every run on the system
+// tenant, has no subject, and gets its row only when a run starts, so a queued
+// job is invisible there. This table holds no payload, error text or logs by
+// design — the tenant learns only that work is waiting, running or finished.
+//
+// One row per BullMQ job. Active rows (queued/running) are kept as they are;
+// a finished row replaces earlier finished rows of the same (tenant, job,
+// subject), so only the latest outcome stays. `subject` is the canonical JSON
+// of the job's declared subjectFields, or NULL for none — stored in clear, so
+// a job must not declare a PII field as its subject.
+export const tenantJobRunsTable = pgTable(
+  "store_tenant_job_runs",
+  {
+    id: serial("id").primaryKey(),
+    tenantId: uuid("tenant_id").notNull(),
+    jobName: text("job_name").notNull(),
+    subject: text("subject"),
+    bullJobId: text("bull_job_id").notNull(),
+    status: text("status").notNull(),
+    queuedAt: instant("queued_at"),
+    startedAt: instant("started_at"),
+    finishedAt: instant("finished_at"),
+    updatedAt: instant("updated_at").default(sql`now()`).notNull(),
+  },
+  (t) => [
+    uniqueIndex("store_tenant_job_runs_bull_job_id_unique").on(t.bullJobId),
+    // Finishing a run prunes older outcomes by this key; the tenant query reads by it.
+    index("store_tenant_job_runs_tenant_job_subject_idx").on(t.tenantId, t.jobName, t.subject),
+    // Stale sweep and retention filter on age alone.
+    index("store_tenant_job_runs_updated_at_idx").on(t.updatedAt),
+  ],
+);
+
+export const tenantJobRunsTableMeta: EntityTableMeta = requireEntityTableMeta(
+  tenantJobRunsTable,
+  "tenantJobRunsTable",
+);

package/packages/bundled-features/src/ledger/changes.json

@@ -1,4 +1,27 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "confirm-schedule-period serializes concurrent confirms of the same schedule period",
+    "detail": "ledger: `confirm-schedule-period` serializes concurrent confirms of the same (tenant, schedule period) with an advisory lock, so direct calls can no longer double-book."
+  },
+  {
+    "version": "0.354.0",
+    "type": "breaking",
+    "title": "Schedule sourceRef is unique per tenant (partial unique index read_ledger_schedules_tenant_id_source_ref_uidx)",
+    "migration": "sourceRef is now unique per tenant: a second createSchedule (or updateSchedule) with a sourceRef already used in the same tenant fails with unique_violation (HTTP 409). Schedules without a sourceRef and the same sourceRef in different tenants stay allowed. Before applying, check for duplicates: SELECT tenant_id, source_ref, count(*) FROM read_ledger_schedules WHERE source_ref IS NOT NULL GROUP BY tenant_id, source_ref HAVING count(*) > 1; and resolve them through real writes (updateSchedule with another sourceRef). kumiko schema generate treats the new unique index on a managed projection as destructive (DROP TABLE + CREATE TABLE + .rebuild.json); a rebuild would also hit the unique index on historical duplicates. Hand-edit the generated migration: replace the generated DROP/CREATE with exactly DROP INDEX IF EXISTS \"read_ledger_schedules_tenant_id_source_ref_idx\"; CREATE UNIQUE INDEX IF NOT EXISTS \"read_ledger_schedules_tenant_id_source_ref_uidx\" ON \"read_ledger_schedules\" (\"tenant_id\", \"source_ref\") WHERE \"source_ref\" IS NOT NULL; and discard the generated .rebuild.json (delete the file, do not commit it). Code that does find-then-create by sourceRef should expect unique_violation on create and re-read the schedule that won the race."
+  },
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "ledger create-transaction and reverse-transaction resolve agent risk high"
+  },
+  {
+    "version": "0.354.0",
+    "type": "breaking",
+    "title": "A ledger schedule needs subjectType and subjectId together or neither",
+    "migration": "Create and update schedule calls that set only one of the two fields now fail validation. Send both fields or neither."
+  },
   {
     "version": "0.331.0",
     "type": "improvement",

package/packages/bundled-features/src/ledger/entity.ts

@@ -108,6 +108,8 @@ export const transactionEntity = createEntity({
       filterable: true,
     }),
   },
+  // Subject ids are only unique within their type, so lookups filter on both
+  // columns; a subjectId-only filter would not be served by this index.
   indexes: [{ columns: ["tenantId", "subjectType", "subjectId"] }],
 });
 
@@ -163,8 +165,8 @@ export const scheduleEntity = createEntity({
       filterable: true,
     }),
     // Caller-assigned stable key (e.g. one id per lease position) to find the
-    // schedule again. Not unique: callers keep their own find-then-create;
-    // `description` stays pure display text instead of a lookup key.
+    // schedule again; unique per tenant when set. `description` stays pure
+    // display text instead of a lookup key.
     sourceRef: createTextField({
       maxLength: 128,
       personal: false,
@@ -172,10 +174,16 @@ export const scheduleEntity = createEntity({
       filterable: true,
     }),
   },
-  // A separate non-unique index: changing the subject index would drop and
-  // recreate it, an additional one is a plain CREATE INDEX.
+  // Find-then-create by sourceRef races across tabs/devices; only the DB closes
+  // that gap. Partial because sourceRef is optional. A new name (not the old
+  // non-unique default) keeps the migration an in-place CREATE UNIQUE INDEX.
   indexes: [
     { columns: ["tenantId", "subjectType", "subjectId"] },
-    { columns: ["tenantId", "sourceRef"] },
+    {
+      columns: ["tenantId", "sourceRef"],
+      unique: true,
+      where: sql`"source_ref" IS NOT NULL`,
+      name: "read_ledger_schedules_tenant_id_source_ref_uidx",
+    },
   ],
 });

package/packages/bundled-features/src/ledger/feature.ts

@@ -31,6 +31,7 @@ import {
   createIncomeStatementHandler,
 } from "./handlers/reports.query.js";
 import { createReverseTransactionHandler } from "./handlers/reverse-transaction.write.js";
+import { requireScheduleSubjectPair } from "./schedule-subject-pair.js";
 
 // Opt-in tier-gating (mirrors folders): when set, the feature declares itself
 // r.toggleable so the dispatcher gate + tier-engine can switch the WHOLE ledger
@@ -125,6 +126,8 @@ function registerLedger(
         "Changes a recurring booking template's description, accounts, amount, interval or date window; use it when a standing order's terms change, already confirmed periods stay booked as they were.",
     }),
   );
+  r.hook("preSave", "schedule:create", requireScheduleSubjectPair);
+  r.hook("preSave", "schedule:update", requireScheduleSubjectPair);
   r.writeHandler(createConfirmSchedulePeriodHandler(access));
   r.queryHandler(
     defineEntityListHandler("schedule", scheduleEntity, {

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

@@ -1,3 +1,4 @@
+import { acquireNamespacedAdvisoryLock } from "@cosmicdrift/kumiko-framework/db";
 import type {
   AccessRule,
   WriteHandlerDef,
@@ -19,6 +20,12 @@ import {
 } from "../schemas.js";
 import { readSubjectReference } from "../subject-reference.js";
 
+// pg_advisory_xact_lock namespace (int4): 'lcsp' as ASCII, disjoint from the
+// framework's other fixed advisory-lock keys.
+const CONFIRM_PERIOD_LOCK_NAMESPACE = 0x6c637370;
+const CONFIRM_PERIOD_LOCK_REASON =
+  "takes the per-(tenant, reference) advisory lock so parallel confirms cannot both pass the already-booked check; TenantDb has no lock API";
+
 // confirm-schedule-period — turn ONE projected period of a schedule into a posted,
 // balanced transaction (debit +amount / credit −amount), tagged with
 // scheduleReference(scheduleId, period) so the host can merge Soll vs. Ist.
@@ -35,6 +42,7 @@ export function createConfirmSchedulePeriodHandler(
     name: "confirm-schedule-period",
     schema: confirmSchedulePeriodPayloadSchema,
     access,
+    escapeHatch: { grants: ["unsafeRaw"], reason: CONFIRM_PERIOD_LOCK_REASON },
     description:
       "Turns one month of a recurring schedule into a posted balanced entry between its debit and credit account, returning the existing booking instead when that period is already booked and not reversed; use it to move a forecast period into the actual books.",
     handler: async (event, ctx) => {
@@ -68,9 +76,13 @@ export function createConfirmSchedulePeriodHandler(
       // normally 0 or 1 row, never O(tenant's-full-history); (2) any Storno
       // that mirrors one of those candidates (a tx is reversed when ANOTHER
       // tx's `reference` names its id).
-      // ponytail: read-then-write, so two confirms racing the same period could
-      // double-book; add a unique index on (tenantId, reference) when concurrent
-      // confirms become real.
+      // No unique index on (tenantId, reference): a Storno makes re-confirming the
+      // same reference legitimate, so the check-then-write is serialized by a lock.
+      await acquireNamespacedAdvisoryLock(
+        ctx.db.unsafeRaw(),
+        CONFIRM_PERIOD_LOCK_NAMESPACE,
+        `${event.user.tenantId}:${reference}`,
+      );
       const candidates = await ctx.db.selectMany(transactionTable, {
         tenantId: event.user.tenantId,
         reference,

package/packages/bundled-features/src/ledger/handlers/create-transaction.write.ts

@@ -19,6 +19,7 @@ export function createCreateTransactionHandler(
     access,
     description:
       "Books one balanced journal entry from a date, description and at least two posting lines summing to zero, after verifying every named account exists; use it to record any financial movement in the tenant's books.",
+    agent: { risk: "high" },
     handler: async (event, ctx) => {
       const payload = event.payload as CreateTransactionPayload; // @cast-boundary engine-payload
 

package/packages/bundled-features/src/ledger/handlers/reverse-transaction.write.ts

@@ -26,6 +26,7 @@ export function createReverseTransactionHandler(
     access,
     description:
       "Books the mirror image of a posted journal entry as a new entry referencing the original, refusing entries that are not posted or already reversed; use it as the only way to correct a booking, since entries themselves are immutable.",
+    agent: { risk: "high" },
     handler: async (event, ctx) => {
       const payload = event.payload as ReverseTransactionPayload; // @cast-boundary engine-payload
 

package/packages/bundled-features/src/ledger/schedule-subject-pair.ts

@@ -0,0 +1,27 @@
+import type { PreSaveHookFn } from "@cosmicdrift/kumiko-framework/engine";
+import { ValidationError } from "@cosmicdrift/kumiko-framework/errors";
+
+function isSet(value: unknown): boolean {
+  return value !== undefined && value !== null && value !== "";
+}
+
+// subjectId is only unique within its subjectType, so a schedule with one of
+// the two would be found by a lone-subjectId filter among other object types.
+// The effective pair is checked (changes over the stored row) because an
+// update may touch only one of the two fields.
+export const requireScheduleSubjectPair: PreSaveHookFn = async (changes, ctx) => {
+  const effective = (key: "subjectType" | "subjectId"): unknown =>
+    key in changes ? changes[key] : ctx.previous[key];
+  const hasType = isSet(effective("subjectType"));
+  const hasId = isSet(effective("subjectId"));
+  if (hasType === hasId) return changes;
+  throw new ValidationError({
+    fields: [
+      {
+        path: hasType ? "subjectId" : "subjectType",
+        code: "required",
+        i18nKey: "errors.validation.required",
+      },
+    ],
+  });
+};

package/packages/bundled-features/src/mail-transport-smtp/feature.ts

@@ -33,8 +33,8 @@ import {
 import {
   BlockedHostError,
   HostResolutionError,
-  MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
   type MailConnectTarget,
+  mailAllowedPrivateHostsEnvSchema,
   readAllowedPrivateMailHostsFromEnv,
   requireDefined,
   requireNonEmpty,
@@ -50,7 +50,6 @@ import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secr
 import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
-import * as z from "zod";
 
 const FEATURE_NAME = "mail-transport-smtp";
 
@@ -59,19 +58,9 @@ const log = createFallbackLogger(FEATURE_NAME);
 // Operator escape hatch for an internal relay or a dev/test SMTP server
 // (mailpit, MailHog): KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS, an operator env
 // var never a tenant-config value, so a tenant can never grant themselves
-// the private-host bypass. Declared here (not duplicated in
-// inbound-provider-imap's envSchema) since both features read the same
-// var and composeEnvSchema rejects two features declaring the same key —
-// see foundation-shared/mail-host-policy.ts for the shared reader + the
-// guard this feeds.
-export const mailTransportSmtpEnvSchema = z.object({
-  [MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR]: z
-    .string()
-    .optional()
-    .describe(
-      "Comma-separated operator allowlist of private/internal hosts (e.g. a local mailpit/greenmail dev server) that bypass the public-address check for SMTP and IMAP host config. Shared with inbound-provider-imap — never a tenant-config value.",
-    ),
-});
+// the private-host bypass. The schema instance is shared with
+// inbound-provider-imap (see foundation-shared/mail-host-policy.ts).
+export const mailTransportSmtpEnvSchema = mailAllowedPrivateHostsEnvSchema;
 
 // Test-only DNS seam — production never calls this, resolveMailConnectTarget
 // defaults to the real resolver. Lets tests pin deterministic, network-free

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

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "breaking",
+    "title": "notes-history adds a composite index on (tenantId, entityType, entityId) for note entries, so the schema-drift check fails until the app regenerates",
+    "detail": "Review batch H2: framework parts of consumer-app findings.\n- `file-derivatives`: the `isPublic` predicate args carry `fileRefId`, so a predicate can reject a client-spoofed FileRef that claims another entity's `entityId`/`fieldName`.\n- `sessions`: `createSessionsFeature({ adminAccess: \"systemAdmin\" })` narrows the admin list/detail queries and both admin screens together (default `\"admin\"`, unchanged).\n- `user-profile`: `change-email` is open to every signed-in user (`openToAll`), so a tenant member whose only role is `TenantAdmin` can change their own email; the handler still re-checks the password.\n- `notes-history`: composite index on `(tenantId, entityType, entityId)` for note entries. Apps run `kumiko-schema generate` after the bump.\n- guards: `// kumiko-lint-ignore a,b reason` suppresses several guards on one line (`lineHasIgnoreTag`); `primitives-discipline` and `no-custom-primitives` honour it.\n- dev-server: `kumiko-build --check` verifies `.kumiko/` is current without writing (exit 1 on drift); `runCodegen` takes `checkOnly`.",
+    "migration": "Run `kumiko-schema generate` in apps that mount notes-history and commit the generated migration."
+  },
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "read_note_mentions gets a tenant, subject index",
+    "migration": "Run `kumiko schema generate`; it emits an in-place CREATE INDEX with no DROP and no rebuild."
+  },
   {
     "version": "0.338.0",
     "type": "improvement",

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

@@ -91,6 +91,8 @@ export function createNoteEntryEntity(
         find: "none",
       }),
     },
+    // Every host detail screen reads its notes by tenant + host entity.
+    indexes: [{ columns: ["tenantId", "entityType", "entityId"] }],
   });
 }
 
@@ -122,6 +124,8 @@ export function createNoteMentionEntity() {
       }),
       subjectId: createTextField({ required: true, maxLength: 64, personal: "ref" }),
     },
+    // The forget cascade looks mentions up by subject within one tenant.
+    indexes: [{ columns: ["tenantId", "subjectId"] }],
   });
 }
 

package/packages/bundled-features/src/personal-access-tokens/handlers/create.write.ts

@@ -66,6 +66,7 @@ export function createPatCreateHandler(opts: CreatePatOptions = {}) {
       },
     },
     escapeHatch: {
+      grants: ["systemIdentity"],
       reason:
         "Reads the caller's own passwordHash (privileged-only field) via ctx.queryAs(SYSTEM, " +
         "user:findForAuth) to re-verify the current password before minting the token. Also " +