@cosmicdrift/kumiko-bundled-features 0.353.0 → 0.354.0

package/dist/jobs/handlers/tenant-runs.query.js

@@ -0,0 +1,72 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { serializeJobSubject } from "@cosmicdrift/kumiko-framework/jobs";
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import { tenantJobRunsTable } from "../tenant-job-run-table.js";
+const DEFAULT_LIMIT = 50;
+function isSubjectEntry(value) {
+    return Array.isArray(value) && typeof value[0] === "string";
+}
+function parseSubject(stored) {
+    if (stored === null)
+        return null;
+    // A corrupt subject must not fail the whole list; parseJsonSafe only
+    // survives a SyntaxError, so the shape needs its own check.
+    const parsed = parseJsonSafe(stored, null);
+    if (!Array.isArray(parsed))
+        return null;
+    return Object.fromEntries(parsed.filter(isSubjectEntry));
+}
+export const tenantRunsQuery = defineQueryHandler({
+    name: "tenant-runs",
+    description: "Lists the calling tenant's own job runs that opted in via tenantVisibleRun — per job and subject every queued or running run plus the latest completed or failed one, active runs first, then newest first; each row carries only status and queuedAt/startedAt/finishedAt, never payloads, error text or logs; the optional subject filter matches exactly: all declared subjectFields with the same JSON types as the job payload; use it to show whether work for a subject is waiting, running or done, and to tell a failed run from a finished one.",
+    schema: z.object({
+        jobName: z.string().optional(),
+        subject: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+        limit: z.number().int().min(1).max(200).optional(),
+    }),
+    // Every membership rank: a run state carries a job name, a status and
+    // times, nothing a team member of the tenant may not see.
+    access: { roles: access.roles("User", "Editor", ...access.admin) },
+    handler: async (query, ctx) => {
+        if (!ctx.systemDb) {
+            throw new InternalError({
+                message: "jobs:query:tenant-runs requires ctx.systemDb (feature must declare r.systemScope())",
+            });
+        }
+        // assertTenantMatch returns the same unfiltered system-mode db — the
+        // explicit tenantId below is the filter, assertRowsTenant the second net.
+        const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+        const where = { tenantId: [query.user.tenantId] };
+        if (query.payload.jobName)
+            where["jobName"] = query.payload.jobName;
+        if (query.payload.subject)
+            where["subject"] = serializeJobSubject(query.payload.subject);
+        const limit = query.payload.limit ?? DEFAULT_LIMIT;
+        const newestFirst = { col: "updatedAt", direction: "desc" };
+        const activeRows = await selectMany(db, tenantJobRunsTable, { ...where, status: { in: ["queued", "running"] } }, { orderBy: newestFirst, limit });
+        const finishedRows = await selectMany(db, tenantJobRunsTable, { ...where, status: { in: ["completed", "failed"] } }, { orderBy: newestFirst, limit });
+        const seenFinishedKeys = new Set();
+        const finishedNewestPerKey = finishedRows.filter((row) => {
+            const key = JSON.stringify([row.jobName, row.subject]);
+            if (seenFinishedKeys.has(key))
+                return false;
+            seenFinishedKeys.add(key);
+            return true;
+        });
+        const activeFirst = [...activeRows, ...finishedNewestPerKey];
+        return {
+            rows: ctx.systemDb.assertRowsTenant(activeFirst.slice(0, limit), "tenantId").map((row) => ({
+                jobName: row.jobName,
+                subject: parseSubject(row.subject),
+                status: row.status,
+                queuedAt: row.queuedAt,
+                startedAt: row.startedAt,
+                finishedAt: row.finishedAt,
+            })),
+            nextCursor: null,
+        };
+    },
+});

package/dist/jobs/index.d.ts

@@ -5,3 +5,5 @@ export { createJobRunLogger } from "./job-run-logger.js";
 export type { JobLogLevel, JobRunStatus } from "./job-run-table.js";
 export { jobRunLogsTable, jobRunsTable } from "./job-run-table.js";
 export { tenantJobFailuresTable } from "./tenant-job-failure-table.js";
+export type { TenantJobRunStatus } from "./tenant-job-run-table.js";
+export { tenantJobRunsTable } from "./tenant-job-run-table.js";

package/dist/jobs/index.js

@@ -3,3 +3,4 @@ export { createJobsFeature } from "./feature.js";
 export { createJobRunLogger } from "./job-run-logger.js";
 export { jobRunLogsTable, jobRunsTable } from "./job-run-table.js";
 export { tenantJobFailuresTable } from "./tenant-job-failure-table.js";
+export { tenantJobRunsTable } from "./tenant-job-run-table.js";

package/dist/jobs/job-run-logger.d.ts

@@ -1,10 +1,10 @@
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { type Registry } from "@cosmicdrift/kumiko-framework/engine";
 import type { JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
 export type JobRunLoggerOptions = {
     readonly db: DbConnection;
     readonly registry: Registry;
 };
-export type JobRunLoggerCallbacks = Pick<JobRunnerOptions, "onJobStart" | "onJobComplete" | "onJobFailed">;
+export type JobRunLoggerCallbacks = Pick<JobRunnerOptions, "onJobStart" | "onJobComplete" | "onJobFailed" | "onJobQueued" | "onJobDropped">;
 export declare function encryptFailureError(error: string, triggeredById: string | null): Promise<string>;
 export declare function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallbacks;

package/dist/jobs/job-run-logger.js

@@ -1,5 +1,6 @@
-import { deleteMany, fetchOne, insertMany, insertOne, updateMany, } from "@cosmicdrift/kumiko-framework/bun-db";
+import { deleteMany, fetchOne, insertMany, insertOnConflictDoNothing, insertOne, transaction, updateMany, upsertOnConflict, } from "@cosmicdrift/kumiko-framework/bun-db";
 import { configuredPiiSubjectKms, encryptPiiValueForSubject, KeyErasedError, PII_ERASED_SENTINEL, } from "@cosmicdrift/kumiko-framework/crypto";
+import { acquireNamespacedAdvisoryLock } from "@cosmicdrift/kumiko-framework/db";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
@@ -8,6 +9,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
 // every connection in the pool.
@@ -92,6 +94,9 @@ async function encryptStartedPayload(payload, triggeredById) {
         return payload;
     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.
@@ -112,14 +117,18 @@ async function recordTenantJobFailure(db, jobName, outcome) {
     // 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(),
+        });
     });
 }
 async function clearTenantJobFailure(db, jobName, outcome) {
@@ -129,7 +138,78 @@ async function clearTenantJobFailure(db, jobName, outcome) {
         return;
     await deleteMany(db, tenantJobFailuresTable, where);
 }
+function tenantRunKey(jobName, tenantId, subject) {
+    // 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, jobName, bullJobId, meta) {
+    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, jobName, bullJobId, meta) {
+    // 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, jobName, bullJobId, outcome, result) {
+    // 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, bullJobId) {
+    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, jobName, bullJobId) {
+    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(write, jobName, bullJobId) {
@@ -191,7 +271,14 @@ export function createJobRunLogger(opts) {
         return { runId, triggeredById };
     }
     return {
+        onJobQueued: async (jobName, bullJobId, meta) => {
+            await isolateTenantRunWrite(() => recordTenantRunQueued(db, jobName, bullJobId, meta), jobName, bullJobId);
+        },
+        onJobDropped: async (jobName, bullJobId) => {
+            await isolateTenantRunWrite(() => dropTenantRunQueued(db, bullJobId), jobName, bullJobId);
+        },
         onJobStart: async (jobName, bullJobId, meta) => {
+            await isolateTenantRunWrite(() => recordTenantRunStarted(db, jobName, bullJobId, meta), jobName, bullJobId);
             const runId = generateId();
             const triggeredById = meta.triggeredById ?? null;
             cachePut(bullJobId, runId, triggeredById);
@@ -227,6 +314,7 @@ export function createJobRunLogger(opts) {
             // clears the tenant's failure record even when the run row itself is
             // unreachable (the state-loss return below).
             await isolateTenantFailureWrite(() => clearTenantJobFailure(db, jobName, outcome), 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
@@ -272,6 +360,7 @@ export function createJobRunLogger(opts) {
             // Mirror of onJobComplete: recorded independently of the run row, so a
             // tenant still learns their job failed if the row is unreachable.
             await isolateTenantFailureWrite(() => recordTenantJobFailure(db, jobName, outcome), 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/dist/jobs/tenant-job-failure-table.js

@@ -1,5 +1,5 @@
 import { requireEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
-import { instant, table as pgTable, serial, sql, text, uuid, } from "@cosmicdrift/kumiko-framework/db";
+import { index, instant, table as pgTable, serial, sql, text, uniqueIndex, uuid, } from "@cosmicdrift/kumiko-framework/db";
 // The tenant's own view of a failed job (fw#3079). Direct-write store like
 // store_job_runs: job-run-logger.ts writes it from the BullMQ callbacks,
 // outside any dispatcher transaction.
@@ -21,5 +21,18 @@ export const tenantJobFailuresTable = pgTable("store_tenant_job_failures", {
     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 = requireEntityTableMeta(tenantJobFailuresTable, "tenantJobFailuresTable");

package/dist/jobs/tenant-job-run-table.d.ts

@@ -0,0 +1,4 @@
+import { type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+export type TenantJobRunStatus = "queued" | "running" | "completed" | "failed";
+export declare const tenantJobRunsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const tenantJobRunsTableMeta: EntityTableMeta;

package/dist/jobs/tenant-job-run-table.js

@@ -0,0 +1,34 @@
+import { requireEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
+import { index, instant, table as pgTable, serial, sql, text, uniqueIndex, uuid, } from "@cosmicdrift/kumiko-framework/db";
+// 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 = requireEntityTableMeta(tenantJobRunsTable, "tenantJobRunsTable");

package/dist/ledger/entity.d.ts

@@ -42,6 +42,7 @@ export declare const accountEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly optionsQuery?: string;
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
         readonly optionsAvailabilityQuery?: string;
+        readonly conditionalOptions?: readonly import("@cosmicdrift/kumiko-types/fields").SelectConditionalOptions<"asset" | "equity" | "expense" | "income" | "liability">[] | undefined;
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
@@ -167,6 +168,7 @@ export declare const transactionEntity: import("@cosmicdrift/kumiko-types/fields
         readonly optionsQuery?: string;
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
         readonly optionsAvailabilityQuery?: string;
+        readonly conditionalOptions?: readonly import("@cosmicdrift/kumiko-types/fields").SelectConditionalOptions<"draft" | "posted">[] | undefined;
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
@@ -299,6 +301,7 @@ export declare const scheduleEntity: import("@cosmicdrift/kumiko-types/fields").
         readonly optionsQuery?: string;
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
         readonly optionsAvailabilityQuery?: string;
+        readonly conditionalOptions?: readonly import("@cosmicdrift/kumiko-types/fields").SelectConditionalOptions<"monthly">[] | undefined;
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };

package/dist/ledger/entity.js

@@ -94,6 +94,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"] }],
 });
 // schedule — a recurring booking template (Dauerauftrag): "book `amount` from
@@ -147,8 +149,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,
@@ -156,10 +158,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/dist/ledger/feature.js

@@ -18,6 +18,7 @@ import { createConfirmSchedulePeriodHandler } from "./handlers/confirm-schedule-
 import { createCreateTransactionHandler } from "./handlers/create-transaction.write.js";
 import { createBalanceSheetHandler, createBalancesReportHandler, createIncomeStatementHandler, } from "./handlers/reports.query.js";
 import { createReverseTransactionHandler } from "./handlers/reverse-transaction.write.js";
+import { requireScheduleSubjectPair } from "./schedule-subject-pair.js";
 function registerLedger(r, access, toggleable) {
     r.describe("Double-entry bookkeeping primitive. Owns two event-sourced entities — the per-tenant `account` chart of accounts (`read_ledger_accounts`, self-referential via parentId, typed asset/liability/equity/income/expense) and immutable `transaction` journal entries (`read_ledger_transactions`) whose balanced posting lines are embedded as jsonb (Σ amount = 0, signed integer minor units). The account catalog uses the generic entity handlers (create, update, list, detail); create-transaction books a balanced entry (Σ=0 and ≥2 distinct accounts enforced at the command boundary, referential integrity against accounts checked) and reverse-transaction books its Storno mirror — there is deliberately NO transaction update/delete, so a posted entry is an immutable fact and the audit trail stays intact. Recurring schedules (`read_ledger_schedules`) layer Dauerauftrag templates on top — a schedule names debit/credit accounts, an amount, a monthly interval and an optional caller-assigned `sourceRef` key (filterable, to find a schedule again), from which the Soll (forecast) is a pure projection (projectSchedule) needing no bookings, and confirm-schedule-period materialises one period as an idempotent, reversal-aware balanced entry referencing scheduleReference(id, period); only confirming writes. Balances and reports (balance sheet, P&L, cashflow) derive as pure queries over the postings. Everything financial — banking, accounting, rent cashflow, credits, invoices — models as accounts + balanced transactions on top. Pin roles with createLedgerFeature({ roles }) or adopt the host model with { access }; pass { toggleable: { default: false } } to tier-gate the whole feature.");
     r.uiHints({
@@ -72,6 +73,8 @@ function registerLedger(r, access, toggleable) {
         access,
         description: "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, {
         access,

package/dist/ledger/handlers/confirm-schedule-period.write.js

@@ -1,3 +1,4 @@
+import { acquireNamespacedAdvisoryLock } from "@cosmicdrift/kumiko-framework/db";
 import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { DEFAULT_LEDGER_ACCESS } from "../constants.js";
@@ -5,6 +6,10 @@ import { accountExecutor, scheduleExecutor, transactionExecutor, transactionTabl
 import { findReversedIds, isoMonth, scheduleReference } from "../recurring.js";
 import { confirmSchedulePeriodPayloadSchema, } 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.
@@ -19,6 +24,7 @@ export function createConfirmSchedulePeriodHandler(access = DEFAULT_LEDGER_ACCES
         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) => {
             const payload = event.payload; // @cast-boundary engine-payload
@@ -42,9 +48,9 @@ export function createConfirmSchedulePeriodHandler(access = DEFAULT_LEDGER_ACCES
             // 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/dist/ledger/handlers/create-transaction.write.js

@@ -14,6 +14,7 @@ export function createCreateTransactionHandler(access = DEFAULT_LEDGER_ACCESS) {
         schema: createTransactionPayloadSchema,
         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; // @cast-boundary engine-payload
             for (const accountId of new Set(payload.lines.map((l) => l.accountId))) {

package/dist/ledger/handlers/reverse-transaction.write.js

@@ -16,6 +16,7 @@ export function createReverseTransactionHandler(access = DEFAULT_LEDGER_ACCESS)
         schema: reverseTransactionPayloadSchema,
         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; // @cast-boundary engine-payload
             const original = await transactionExecutor.detail({ id: payload.id }, event.user, ctx.db);

package/dist/ledger/schedule-subject-pair.d.ts

@@ -0,0 +1,2 @@
+import type { PreSaveHookFn } from "@cosmicdrift/kumiko-framework/engine";
+export declare const requireScheduleSubjectPair: PreSaveHookFn;

package/dist/ledger/schedule-subject-pair.js

@@ -0,0 +1,24 @@
+import { ValidationError } from "@cosmicdrift/kumiko-framework/errors";
+function isSet(value) {
+    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 = async (changes, ctx) => {
+    const effective = (key) => 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/dist/mail-transport-smtp/feature.d.ts

@@ -1,8 +1,7 @@
 import type { lookup } from "node:dns/promises";
-import * as z from "zod";
-export declare const mailTransportSmtpEnvSchema: z.ZodObject<{
-    KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
+export declare const mailTransportSmtpEnvSchema: import("zod").ZodObject<{
+    KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
 export declare function setSmtpMailHostLookup(fn: typeof lookup | undefined): void;
 export declare const mailTransportSmtpFeature: import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
     readonly exports: {

package/dist/mail-transport-smtp/feature.js

@@ -25,29 +25,20 @@
 //   - `config` — für die Tenant-Config-Keys
 //   - `secrets` — für das verschlüsselte SMTP-Password
 import { createSmtpTransport, } from "@cosmicdrift/kumiko-bundled-features/channel-email";
-import { BlockedHostError, HostResolutionError, MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR, readAllowedPrivateMailHostsFromEnv, requireDefined, requireNonEmpty, requireSecretSet, resolveMailConnectTarget, } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import { BlockedHostError, HostResolutionError, mailAllowedPrivateHostsEnvSchema, readAllowedPrivateMailHostsFromEnv, requireDefined, requireNonEmpty, requireSecretSet, resolveMailConnectTarget, } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import { MAIL_TRANSPORT_EXTENSION, } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 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";
 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
 // host resolutions instead of depending on real DNS for a placeholder host.

package/dist/notes-history/entity.js

@@ -81,6 +81,8 @@ export function createNoteEntryEntity(access, parents) {
                 find: "none",
             }),
         },
+        // Every host detail screen reads its notes by tenant + host entity.
+        indexes: [{ columns: ["tenantId", "entityType", "entityId"] }],
     });
 }
 export const noteEntryEntity = createNoteEntryEntity();
@@ -109,6 +111,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"] }],
     });
 }
 export const noteMentionEntity = createNoteMentionEntity();

package/dist/personal-access-tokens/handlers/create.write.js

@@ -41,6 +41,7 @@ export function createPatCreateHandler(opts = {}) {
             },
         },
         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 " +
                 "reads the MFA enrollment of the user being re-authenticated via the mfaVerifier callback.",

package/dist/sessions/feature.d.ts

@@ -3,6 +3,7 @@ import { type SessionAllOthersRevoker, type SessionMassRevoker } from "./session
 export type SessionsFeatureOptions = {
     readonly autoRevokeOnPasswordChange?: SessionMassRevoker;
     readonly expiresInMs?: number;
+    readonly adminAccess?: "admin" | "systemAdmin";
 };
 export type BindAutoRevokeOnPasswordChange = (revoker: SessionMassRevoker) => void;
 export type BindRevokeAllOtherSessions = (revoker: SessionAllOthersRevoker) => void;