@cosmicdrift/kumiko-framework 0.399.0 → 0.401.0

package/dist/db/event-store-executor-read-search.js

@@ -6,6 +6,7 @@ import { LIST_ROW_META_REFERENCES } from "../ui-types/list-row-meta.js";
 import { hasSearchablePlaintext, isSensitiveLabelField } from "./entity-field-encryption.js";
 import { bindPlaceholders } from "./event-store-executor-read-filter.js";
 import { executeRawQueryRead } from "./queries/raw-sql.js";
+import { resolveReadOwnership } from "./read-ownership.js";
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
 import { schemaTableName } from "./table-introspection.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
@@ -42,6 +43,12 @@ function collectReferenceSearchDescriptors(table, referenceSearch, dbMode) {
     }
     return descriptors;
 }
+// The target of a reference is gated like a direct read of it (access rule, parent-ref and
+// readGate): a label of a row the viewer cannot open must not be findable by searching or
+// readable by ordering.
+export function referenceTargetOwnership(targetEntity, targetTable, targetTableName, user, db, parentVisibility) {
+    return resolveReadOwnership({ entity: targetEntity, table: targetTable }, targetTableName, user, db, parentVisibility, { includeDeleted: false, narrowTypes: undefined });
+}
 // Matches the main list's own default: soft-deleted rows are invisible, so a
 // deleted target must neither match a search nor influence an ordering.
 export function isSoftDeletedTargetHidden(targetEntity, targetTable) {
@@ -51,13 +58,13 @@ export function isSoftDeletedTargetHidden(targetEntity, targetTable) {
 // unscoped SQL, a match in a foreign tenant must never surface a row here.
 // Mirrors the main table's own tenant filter (see the `table["tenantId"]`
 // check further down in list()).
-async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db) {
+async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db, parentVisibility) {
     // The label must not leak through match counts: a viewer who cannot read the
     // target row or its label field would otherwise probe names by searching.
     const labelAccess = buildOwnershipClause(user, normalizeAccessEntry(targetEntity.fields[descriptor.labelField]?.access?.read), targetTable);
     if (labelAccess.kind !== "pass")
         return undefined;
-    const ownership = buildOwnershipClause(user, targetEntity.access?.read, targetTable);
+    const ownership = referenceTargetOwnership(targetEntity, targetTable, targetTableName, user, db, parentVisibility);
     if (ownership.kind === "empty")
         return undefined;
     const labelCol = physicalColumnName(targetTable, descriptor.labelField);
@@ -91,7 +98,7 @@ async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEnt
 }
 // Same lookup, but the target's index is tenant-wide, not per-viewer, so
 // candidate ids get re-checked against the target entity's own read access.
-async function resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db, searchAdapter) {
+async function resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db, searchAdapter, parentVisibility) {
     const searchTenantId = targetEntity.systemStream ? SYSTEM_TENANT_ID : user.tenantId;
     const results = await searchAdapter.search(searchTenantId, searchTerm, {
         filterType: descriptor.targetEntityName,
@@ -101,7 +108,7 @@ async function resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, tar
         // skip: no match, or over the cap — same drop-the-clause policy as the ILIKE path
         return undefined;
     }
-    const ownership = buildOwnershipClause(user, targetEntity.access?.read, targetTable);
+    const ownership = referenceTargetOwnership(targetEntity, targetTable, targetTableName, user, db, parentVisibility);
     if (ownership.kind === "empty")
         return undefined;
     const candidateIds = results.map((r) => String(r.entityId));
@@ -132,7 +139,7 @@ async function resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, tar
         return undefined;
     return { ownColumn: descriptor.ownColumn, ids: rows.map((r) => r.id) };
 }
-async function resolveReferenceMatches(descriptor, searchTerm, resolveEntity, db, user, searchAdapter) {
+async function resolveReferenceMatches(descriptor, searchTerm, resolveEntity, db, user, searchAdapter, resolveTable, parentVisibility) {
     const targetEntity = resolveEntity(descriptor.targetEntityName);
     if (targetEntity === undefined) {
         // skip: unknown target entity — registry inconsistency the boot-validator
@@ -145,17 +152,18 @@ async function resolveReferenceMatches(descriptor, searchTerm, resolveEntity, db
         // `name` is a declared field on the tenant entity, not an id/row-meta column
         return undefined;
     }
-    const targetTable = referenceTargetTable(descriptor.targetEntityName, targetEntity);
+    const targetTable = resolveTable?.(descriptor.targetEntityName) ??
+        referenceTargetTable(descriptor.targetEntityName, targetEntity);
     const targetTableName = String(schemaTableName(targetTable));
     if (!isSensitiveLabelField(targetEntity, descriptor.labelField)) {
-        return resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db);
+        return resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db, parentVisibility);
     }
     if (!hasSearchablePlaintext(targetEntity, descriptor.labelField)) {
         // skip: no plaintext anywhere to match — boot rejects this normally,
         // this is defense-in-depth for a target entity resolved only at runtime.
         return undefined;
     }
-    return resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db, searchAdapter);
+    return resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db, searchAdapter, parentVisibility);
 }
 // Building the table is pure but not free, and runs on every search request;
 // keyed by the definition object so a re-registered entity never sees a stale table.
@@ -216,6 +224,6 @@ async function resolveSearchableReferenceMatches(request, searchAdapter) {
     // to infer its value by matching the target's label — same probe
     // surface as filtering/sorting on it directly.
     const descriptors = collectReferenceSearchDescriptors(request.table, referenceSearch, request.db.mode).filter((d) => request.fieldReadClause(d.ownColumn).kind === "pass");
-    const matches = await Promise.all(descriptors.map((d) => resolveReferenceMatches(d, request.searchTerm, referenceSearch.resolveEntity, request.db, request.user, searchAdapter)));
+    const matches = await Promise.all(descriptors.map((d) => resolveReferenceMatches(d, request.searchTerm, referenceSearch.resolveEntity, request.db, request.user, searchAdapter, referenceSearch.resolveTable, request.parentVisibility)));
     return matches.filter((m) => m !== undefined);
 }

package/dist/db/event-store-executor-read-sort.d.ts

@@ -4,6 +4,7 @@ import type { SessionUser } from "../engine/types/index.ts";
 import type { EventStoreExecutor } from "./event-store-executor.ts";
 import type { Table } from "./event-store-executor-context.ts";
 import type { ListWhere } from "./event-store-executor-read-filter.ts";
+import type { ParentVisibilityOption } from "./parent-ref-clause.ts";
 import type { TenantDb } from "./tenant-db.ts";
 type ListPayload = Parameters<EventStoreExecutor["list"]>[0];
 type ReferenceSortOption = NonNullable<Parameters<EventStoreExecutor["list"]>[3]>["referenceSort"];
@@ -15,16 +16,20 @@ export type ListSort = {
     readonly descending: boolean;
     readonly nulls: SortNulls | undefined;
 } | {
-    readonly kind: "referenceLabel";
+    readonly kind: "expression";
     readonly field: string;
     readonly descending: boolean;
     readonly nulls: SortNulls | undefined;
-    readonly labelSql: (params: unknown[]) => string;
+    readonly sql: (params: unknown[]) => string;
 };
 export type SortedListSort = Exclude<ListSort, {
     readonly kind: "unsorted";
 }>;
 export declare function sortsNullsFirst(sort: SortedListSort): boolean;
+export declare function buildReferenceSortExpr(outerColumnSql: string, descriptor: {
+    readonly targetEntityName: string;
+    readonly labelField: string;
+}, resolveEntity: (entityName: string) => EntityDefinition | undefined, db: TenantDb, user: SessionUser, resolveTable: ((entityName: string) => Table) | undefined, parentVisibility: ParentVisibilityOption | undefined): ((params: unknown[]) => string) | undefined;
 export declare function resolveListSort(request: {
     readonly payload: Pick<ListPayload, "sort" | "sortDirection">;
     readonly table: Table;
@@ -33,8 +38,10 @@ export declare function resolveListSort(request: {
     readonly colSql: (field: string) => string;
     readonly fieldReadClause: (field: string) => OwnershipClause;
     readonly referenceSort: ReferenceSortOption;
+    readonly derivedSortExpr?: (field: string) => ((params: unknown[]) => string) | undefined;
     readonly db: TenantDb;
     readonly user: SessionUser;
+    readonly parentVisibility: ParentVisibilityOption | undefined;
 }): ListSort;
 export declare function renderSortSql(sort: SortedListSort, where: ListWhere): string;
 export declare function renderListOrderBy(sort: ListSort, where: ListWhere): {

package/dist/db/event-store-executor-read-sort.js

@@ -1,12 +1,14 @@
 import { buildOwnershipClause, normalizeAccessEntry, shiftParams, } from "../engine/ownership.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { isListSortAllowed, isSensitiveLabelField } from "./entity-field-encryption.js";
-import { isSoftDeletedTargetHidden } from "./event-store-executor-read-search.js";
+import { isSoftDeletedTargetHidden, referenceTargetOwnership, } from "./event-store-executor-read-search.js";
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
 import { schemaTableName } from "./table-introspection.js";
 // Projected alongside the row when a reference sort is active, so the keyset
 // cursor carries the label that was ordered by instead of the FK's UUID.
 const SORT_LABEL_ALIAS = "__kumiko_sort_label";
+// Where-rules qualify with the table name they get; the target may be the outer entity itself.
+const TARGET_ALIAS = "t";
 function declaredSortNulls(entity, field) {
     const def = entity.fields[field];
     return def !== undefined && "sortNulls" in def ? def.sortNulls : undefined;
@@ -28,7 +30,7 @@ function nullsClause(sort) {
 // undefined means "cannot order by this label", which drops the sort to plain
 // id order; falling back to the UUID column would look deliberate to the user
 // while being arbitrary, which is worse than no sorting.
-function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolveEntity, db, user) {
+export function buildReferenceSortExpr(outerColumnSql, descriptor, resolveEntity, db, user, resolveTable, parentVisibility) {
     const targetEntity = resolveEntity(descriptor.targetEntityName);
     if (targetEntity === undefined) {
         // skip: unknown target entity — registry inconsistency the boot-validator
@@ -44,15 +46,16 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
         // arbitrary to the reader and would also rank rows by their stored secret
         return undefined;
     }
-    const targetTable = buildEntityTable(descriptor.targetEntityName, targetEntity);
+    const targetTable = resolveTable?.(descriptor.targetEntityName) ??
+        buildEntityTable(descriptor.targetEntityName, targetEntity);
     // The order of labels the viewer may not read would leak them bit by bit, same as the search path.
-    const labelAccess = buildOwnershipClause(user, normalizeAccessEntry(targetEntity.fields[descriptor.labelField]?.access?.read), targetTable);
+    const labelAccess = buildOwnershipClause(user, normalizeAccessEntry(targetEntity.fields[descriptor.labelField]?.access?.read), targetTable, 1, TARGET_ALIAS);
     if (labelAccess.kind !== "pass")
         return undefined;
-    const ownership = buildOwnershipClause(user, targetEntity.access?.read, targetTable);
+    const targetTableName = String(schemaTableName(targetTable));
+    const ownership = referenceTargetOwnership(targetEntity, targetTable, TARGET_ALIAS, user, db, parentVisibility);
     if (ownership.kind === "empty")
         return undefined;
-    const targetTableName = String(schemaTableName(targetTable));
     const labelCol = physicalColumnName(targetTable, descriptor.labelField);
     const tenantScoped = targetTable["tenantId"] !== undefined && db.mode === "tenant";
     const tenantCol = tenantScoped ? physicalColumnName(targetTable, "tenantId") : "";
@@ -77,11 +80,21 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
             ownershipClause = ` AND ${shifted.sqlText}`;
         }
         return (`(SELECT t."${labelCol}" FROM "${targetTableName}" t ` +
-            `WHERE t."id" = "${outerTableName}".${ownColumnSql}${tenantClause}${ownershipClause}${deletedClause})`);
+            `WHERE t."id" = ${outerColumnSql}${tenantClause}${ownershipClause}${deletedClause})`);
     };
 }
 export function resolveListSort(request) {
     const { payload, table, entity, referenceSort } = request;
+    const derivedSql = payload.sort ? request.derivedSortExpr?.(payload.sort) : undefined;
+    if (derivedSql !== undefined && payload.sort) {
+        return {
+            kind: "expression",
+            field: payload.sort,
+            descending: payload.sortDirection === "desc",
+            nulls: undefined,
+            sql: derivedSql,
+        };
+    }
     // A column sort must not 400 (the renderer sends one per header click), and the order of
     // ciphertext carries no meaning for the user while leaking the order of the plaintext.
     const field = payload.sort &&
@@ -101,15 +114,15 @@ export function resolveListSort(request) {
     // directly: either the field opted into `sortable` and we order by the
     // target row's label, or the sort is dropped to plain id order.
     const descriptor = referenceSort?.fields.find((f) => f.fieldName === field);
-    const labelSql = referenceSort && descriptor
-        ? buildReferenceSortExpr(request.tableName, request.colSql(field), descriptor, referenceSort.resolveEntity, request.db, request.user)
+    const sql = referenceSort && descriptor
+        ? buildReferenceSortExpr(`"${request.tableName}".${request.colSql(field)}`, descriptor, referenceSort.resolveEntity, request.db, request.user, referenceSort.resolveTable, request.parentVisibility)
         : undefined;
-    return labelSql === undefined
+    return sql === undefined
         ? { kind: "unsorted" }
-        : { kind: "referenceLabel", field, descending, nulls, labelSql };
+        : { kind: "expression", field, descending, nulls, sql };
 }
 export function renderSortSql(sort, where) {
-    return sort.kind === "referenceLabel" ? sort.labelSql(where.params) : where.colSql(sort.field);
+    return sort.kind === "expression" ? sort.sql(where.params) : where.colSql(sort.field);
 }
 export function renderListOrderBy(sort, where) {
     const idAscending = `${where.colSql("id")} ASC`;
@@ -124,7 +137,7 @@ export function renderListOrderBy(sort, where) {
             sortLabelProjection: "",
         };
     }
-    // The projected label alias is ordered by directly, so Postgres evaluates
+    // The projected alias is ordered by directly, so Postgres evaluates
     // the correlated subquery once per row instead of once for ORDER BY and
     // once for the SELECT list. Projecting it also lets the keyset cursor carry
     // the value that was ordered by rather than the FK column's UUID.
@@ -137,7 +150,7 @@ export function renderListOrderBy(sort, where) {
 // stripped before coercion; the last row's label feeds the keyset cursor.
 export function takeLastSortLabel(rawRows, sort) {
     const lastSortLabel = rawRows[rawRows.length - 1]?.[SORT_LABEL_ALIAS];
-    if (sort.kind === "referenceLabel") {
+    if (sort.kind === "expression") {
         for (const row of rawRows)
             delete row[SORT_LABEL_ALIAS];
     }

package/dist/db/event-store-executor-read-where.d.ts

@@ -3,15 +3,10 @@ import type { SessionUser } from "../engine/types/index.ts";
 import type { EventStoreExecutor } from "./event-store-executor.ts";
 import type { ExecutorContext } from "./event-store-executor-context.ts";
 import { type ListWhere } from "./event-store-executor-read-filter.ts";
-import { type ParentVisibilityOption } from "./parent-ref-clause.ts";
 import type { TenantDb } from "./tenant-db.ts";
 export type ListRuntimeOptions = NonNullable<Parameters<EventStoreExecutor["list"]>[3]>;
 export type ListWherePayload = Pick<Parameters<EventStoreExecutor["list"]>[0], "search" | "filter" | "filters">;
 export type FieldReadClause = (field: string) => OwnershipClause;
-export declare function resolveReadOwnership(ctx: Pick<ExecutorContext, "entity" | "table">, tableName: string, user: SessionUser, db: TenantDb, parentVisibility: ParentVisibilityOption | undefined, gate: {
-    readonly includeDeleted: boolean;
-    readonly narrowTypes: ReadonlySet<string> | undefined;
-}): OwnershipClause;
 export declare function createFieldReadClause(ctx: Pick<ExecutorContext, "entity" | "table">, user: SessionUser): FieldReadClause;
 export type ListWhereBuild = {
     readonly kind: "empty";

package/dist/db/event-store-executor-read-where.js

@@ -1,17 +1,10 @@
-import { buildOwnershipClause, combineClauses, normalizeAccessEntry, } from "../engine/ownership.js";
+import { buildOwnershipClause, normalizeAccessEntry, } from "../engine/ownership.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { appendShiftedClause, applyListFilter, collectListFilters, deriveParentNarrowTypes, } from "./event-store-executor-read-filter.js";
 import { applyListSearch } from "./event-store-executor-read-search.js";
-import { buildParentRefClause } from "./parent-ref-clause.js";
+import { resolveReadOwnership } from "./read-ownership.js";
 import { physicalColumnName } from "./table-builder.js";
 import { schemaTableName } from "./table-introspection.js";
-// H.2 — entity-level read ownership, AND-ed with the parent-ref read-gate
-// (join-row entities derive their visibility from a host row's own read path —
-// see db/parent-ref-clause.ts). `empty` means there's no row the user could ever see.
-export function resolveReadOwnership(ctx, tableName, user, db, parentVisibility, gate) {
-    const parentClause = buildParentRefClause(ctx.entity, ctx.table, tableName, user, db, parentVisibility, gate);
-    return combineClauses(buildOwnershipClause(user, ctx.entity.access?.read, ctx.table), parentClause);
-}
 // Replicates TenantDb's readWhere semantics for the raw list SQL.
 function appendTenantAndSoftDeleteScope(where, ctx, db, includeDeleted) {
     if (ctx.table["tenantId"] !== undefined && db.mode === "tenant") {
@@ -62,6 +55,7 @@ export async function buildListWhere(ctx, payload, user, db, runtimeOptions) {
             entityName,
             table,
             referenceSearch: runtimeOptions?.referenceSearch,
+            parentVisibility: runtimeOptions?.parentVisibility,
             fieldReadClause,
             streamTenantFor,
             user,

package/dist/db/event-store-executor-read.js

@@ -1,11 +1,13 @@
 import { executeRawQueryRead } from "../db/queries/raw-sql.js";
 import { extractTableInfo } from "../db/table-info.js";
 import { getStreamVersion } from "../event-store/index.js";
+import { buildDerivedSelect } from "./derived-field-sql.js";
 import { aggregateList } from "./event-store-executor-read-aggregate.js";
 import { appendCursorBoundary, countListRows, encodeNextCursor, resolveListPagination, } from "./event-store-executor-read-paging.js";
 import { appendStreamVersionProjection, coerceAndRehydrateRow, takeStreamVersions, withStreamVersion, } from "./event-store-executor-read-rows.js";
 import { renderListOrderBy, resolveListSort, takeLastSortLabel, } from "./event-store-executor-read-sort.js";
-import { buildListWhere, resolveReadOwnership } from "./event-store-executor-read-where.js";
+import { buildListWhere } from "./event-store-executor-read-where.js";
+import { resolveReadOwnership } from "./read-ownership.js";
 import { schemaTableName } from "./table-introspection.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
 // The read verbs (list/aggregate/detail) of the event-store-executor. Split out
@@ -30,6 +32,15 @@ export function createReadVerbs(ctx) {
             if (built.kind === "empty")
                 return emptyListPage(totalCount);
             const { where, fieldReadClause, searchTruncated } = built;
+            const derived = buildDerivedSelect({
+                entity,
+                table,
+                tableName,
+                fieldReadClause,
+                user,
+                db,
+                runtime: runtimeOptions,
+            });
             const sort = resolveListSort({
                 payload,
                 table,
@@ -38,8 +49,10 @@ export function createReadVerbs(ctx) {
                 colSql: where.colSql,
                 fieldReadClause,
                 referenceSort: runtimeOptions?.referenceSort,
+                derivedSortExpr: derived?.sortExpr,
                 db,
                 user,
+                parentVisibility: runtimeOptions?.parentVisibility,
             });
             if (payload.cursor)
                 appendCursorBoundary(where, payload.cursor, sort);
@@ -51,24 +64,30 @@ export function createReadVerbs(ctx) {
             const offsetClause = !payload.cursor && offset > 0 ? ` OFFSET ${offset}` : "";
             const whereClauseSqlText = where.whereSql.length > 0 ? ` WHERE ${where.whereSql.join(" AND ")}` : "";
             const streamVersionProjection = appendStreamVersionProjection(where.params, tableName, streamTenantFor(user));
-            const selectList = `*${sortLabelProjection}${streamVersionProjection}`;
+            const derivedProjection = derived?.projections(where.params) ?? "";
+            const selectList = `*${sortLabelProjection}${streamVersionProjection}${derivedProjection}`;
             const listSql = `SELECT ${selectList} FROM "${tableName}"${whereClauseSqlText}${orderByClause} LIMIT ${limit}${offsetClause}`;
             const rawRows = await executeRawQueryRead(runner, listSql, where.params);
             const lastSortLabel = takeLastSortLabel(rawRows, sort);
             const streamVersions = takeStreamVersions(rawRows);
+            const derivedValues = derived?.takeValues(rawRows);
             const tableInfo = extractTableInfo(table);
             const encryptedRows = rawRows.map((r) => coerceAndRehydrateRow(r, tableInfo, entity));
             const decryptedRows = await Promise.all(encryptedRows.map((r) => decryptForRead(r, { degradeUndecryptable: () => { } })));
             // Stream version is authoritative (see detail()): ctx.events.append bumps the
             // stream without touching row.version, so the raw row version would hand
             // clients a stale optimistic-lock base. Rows without events keep theirs.
-            const rows = decryptedRows.map((r, i) => withStreamVersion(r, streamVersions[i] ?? 0));
+            const storedRows = decryptedRows.map((r, i) => withStreamVersion(r, streamVersions[i] ?? 0));
             // Cache the still-encrypted raw rows (read-row version): same at-rest guarantee as
             // detail()'s encryptForStorage round-trip, without a re-encrypt; detail() rejects
             // a cached version that differs from the stream.
-            if (entityCache && entityName && rows.length > 0) {
+            if (entityCache && entityName && storedRows.length > 0) {
                 await entityCache.mset(user.tenantId, entityName, encryptedRows.map((r) => ({ id: r["id"], data: r })));
             }
+            // Viewer-dependent, so attached only after the cache write, as new row objects.
+            const rows = derivedValues === undefined
+                ? storedRows
+                : storedRows.map((r, i) => ({ ...r, ...derivedValues[i] }));
             const lastRow = rows[rows.length - 1];
             const lastRaw = rawRows[rawRows.length - 1];
             let nextCursor = null;

package/dist/db/event-store-executor-write-steps.d.ts

@@ -1,13 +1,18 @@
 import type { EntityId } from "@cosmicdrift/kumiko-types/identifiers";
 import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import type { ZodType } from "zod";
-import type { UnavailableSelectOption } from "../engine/screen-helpers.ts";
+import { type UnavailableSelectOption } from "../engine/screen-helpers.ts";
+import type { FieldDefinition } from "../engine/types/fields.ts";
 import type { UnprocessableOpts } from "../errors/classes.ts";
 import { type WriteFailure, writeFailure } from "../errors/index.ts";
 import type { StoredEvent } from "../event-store/index.ts";
 import type { DbRow, DbRunner } from "./connection.ts";
 export declare function projectEntityEvent(db: TenantDb, runner: DbRunner, event: StoredEvent): Promise<void>;
 export declare function selectOptionNotAvailableFailure(entries: readonly UnavailableSelectOption[]): WriteFailure | undefined;
+export declare function missingConditionalRequirementFailure(paths: readonly string[]): WriteFailure | undefined;
+/** Value-consistency checks on the merged row (create: no `previous`): options a
+ *  conditionalOptions rule no longer allows, and requiredWhen values still missing. */
+export declare function fieldStateFailure(fields: Readonly<Record<string, FieldDefinition>>, values: Record<string, unknown>, previous?: Record<string, unknown>): WriteFailure | undefined;
 export type PreSaveFn = (changes: Record<string, unknown>, previous: Record<string, unknown>, isNew: boolean) => Promise<Record<string, unknown>>;
 export declare function runPreSave(preSave: PreSaveFn | undefined, changes: Record<string, unknown>, previous: Record<string, unknown>, isNew: boolean, entityName: string, action: "create" | "update", outputSchema: () => ZodType): Promise<{
     readonly data: DbRow;

package/dist/db/event-store-executor-write-steps.js

@@ -1,4 +1,6 @@
-import { VersionConflictError as FrameworkVersionConflict, UnprocessableError, writeFailure, } from "../errors/index.js";
+import { findMissingConditionalRequirements } from "../engine/field-state.js";
+import { findUnavailableSelectOptions, } from "../engine/screen-helpers.js";
+import { VersionConflictError as FrameworkVersionConflict, UnprocessableError, ValidationError, writeFailure, } from "../errors/index.js";
 import { hasLiveProjectionsForEvent, runProjectionsForEvent, } from "../pipeline/projections-runner.js";
 import { projectionRegistryOf } from "./projection-registry-binding.js";
 import { runInSavepointIfSupported } from "./query.js";
@@ -35,6 +37,23 @@ export function selectOptionNotAvailableFailure(entries) {
         },
     }));
 }
+export function missingConditionalRequirementFailure(paths) {
+    if (paths.length === 0)
+        return undefined;
+    return writeFailure(new ValidationError({
+        fields: paths.map((path) => ({
+            path,
+            code: "required",
+            i18nKey: "kumiko.validation.required",
+        })),
+    }));
+}
+/** Value-consistency checks on the merged row (create: no `previous`): options a
+ *  conditionalOptions rule no longer allows, and requiredWhen values still missing. */
+export function fieldStateFailure(fields, values, previous) {
+    return (selectOptionNotAvailableFailure(findUnavailableSelectOptions(fields, values, previous)) ??
+        missingConditionalRequirementFailure(findMissingConditionalRequirements(fields, values, previous)));
+}
 // preSave runs before ownership checks: authorization must evaluate the row
 // as it will actually be persisted, including hook-derived fields. A throwing
 // hook is an app-author bug (bad business rule, not a framework fault) — map it

package/dist/db/event-store-executor-write.js

@@ -3,7 +3,7 @@ import { checkWriteFieldOwnership } from "../engine/field-access.js";
 import { instructionFieldNames } from "../engine/instruction-fields.js";
 import { userCanCreateFieldRow, userCanWriteFieldRow } from "../engine/ownership.js";
 import { buildInsertSchema, buildUpdateSchema } from "../engine/schema-builder.js";
-import { findUnavailableSelectOptions, isRecordLocked, isUnchangedValue, } from "../engine/screen-helpers.js";
+import { isRecordLocked, isUnchangedValue } from "../engine/screen-helpers.js";
 import { IdempotentReplayError, PreconditionFailedError, RecordLockedError, } from "../errors/classes.js";
 import { AccessDeniedError, VersionConflictError as FrameworkVersionConflict, InternalError, NotFoundError, UnprocessableError, writeFailure, } from "../errors/index.js";
 import { isSubjectErasedConflict } from "../errors/subject-erased.js";
@@ -15,7 +15,7 @@ import { applyEntityEvent } from "./apply-entity-event.js";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types.js";
 import { WritePurposes, } from "./event-store-executor.js";
 import { buildEventMetadata, entityEventName, isForeignTenantOnGlobalEntity, ownershipSubject, tryMapUniqueViolation, } from "./event-store-executor-context.js";
-import { optimisticLockFailure, ownershipDeniedFailure, projectEntityEvent, runPreSave, selectOptionNotAvailableFailure, } from "./event-store-executor-write-steps.js";
+import { fieldStateFailure, optimisticLockFailure, ownershipDeniedFailure, projectEntityEvent, runPreSave, } from "./event-store-executor-write-steps.js";
 import { isFrameworkSystemUser, isLockGuardBypassed } from "./lock-guard.js";
 import { runInSavepointIfSupported } from "./query.js";
 import { assertPersonalDataWrite, tableNameOf, withExecutorManagedWrites } from "./tenant-db.js";
@@ -241,9 +241,9 @@ export function createWriteVerbs(ctx) {
         // Statutory retention/erasure writes may change a condition field (e.g. null a PII
         // reference) and must not be blocked by the select rule — same exemption as the lock.
         const isStatutorySystemWrite = options?.writePurpose !== undefined && isFrameworkSystemUser(user);
-        return isStatutorySystemWrite
-            ? undefined
-            : selectOptionNotAvailableFailure(findUnavailableSelectOptions(entity.fields, mergedNew, previous));
+        if (isStatutorySystemWrite)
+            return undefined;
+        return fieldStateFailure(entity.fields, mergedNew, previous);
     }
     async function appendCreatedEvent(runner, user, streamTenantId, aggregateId, flatData) {
         // 1. Append the event in the same transaction as the projection write — both must
@@ -446,9 +446,9 @@ export function createWriteVerbs(ctx) {
             const ownershipDenied = createOwnershipFailure(user, streamTenantId, payloadWithoutId, data);
             if (ownershipDenied)
                 return ownershipDenied;
-            const unavailableOnCreate = selectOptionNotAvailableFailure(findUnavailableSelectOptions(entity.fields, data));
-            if (unavailableOnCreate)
-                return unavailableOnCreate;
+            const invalidFieldState = fieldStateFailure(entity.fields, data);
+            if (invalidFieldState)
+                return invalidFieldState;
             // All compound types (locatedTimestamp, money, ...) use the same pipeline: the
             // caller sends the combined API form, the framework stores the flat DB form (see
             // db/compound-types.ts).

package/dist/db/money.d.ts

@@ -1,5 +1,6 @@
 import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
 import { toMinorUnits } from "../engine/minor-units.ts";
+export declare const FRAMEWORK_DEFAULT_CURRENCY: "EUR";
 export { toMinorUnits };
 export declare function moneyPayloadToMinorUnits(raw: unknown): number | undefined;
 export declare function flattenMoney(payload: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;
@@ -29,3 +30,6 @@ export type MoneyRead = {
  * Pure — does not mutate its input.
  */
 export declare function rehydrateMoney(row: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;
+/** One money value from its raw amount/currency columns; shared with SQL derived money so both
+ *  produce the identical read shape. Throws on a corrupt amount. */
+export declare function readMoney(name: string, amountRaw: unknown, currencyRaw: unknown, fallbackCurrency: string): MoneyRead;

package/dist/db/money.js

@@ -32,7 +32,7 @@ import { DEFAULT_CURRENCIES } from "../engine/field-helpers.js";
 // amount column (legacy DB convention for money — `SUM(buying_price)` remains
 // idiomatic). `<name>Currency` is the additional column.
 import { MINOR_UNIT_SCALE, toMinorUnits } from "../engine/minor-units.js";
-const FRAMEWORK_DEFAULT_CURRENCY = DEFAULT_CURRENCIES[0]; // "EUR"
+export const FRAMEWORK_DEFAULT_CURRENCY = DEFAULT_CURRENCIES[0]; // "EUR"
 export { toMinorUnits };
 function toMajorUnits(amountScaled) {
     return amountScaled / MINOR_UNIT_SCALE;
@@ -116,35 +116,40 @@ export function rehydrateMoney(row, entity) {
             delete result[name];
             continue;
         }
-        let amountScaled;
-        if (typeof amountRaw === "number") {
-            amountScaled = amountRaw;
-        }
-        else if (typeof amountRaw === "bigint") {
-            amountScaled = Number(amountRaw);
-            if (!Number.isSafeInteger(amountScaled)) {
-                throw new Error(`rehydrateMoney: field "${name}" bigint amount is not a safe integer`);
-            }
-        }
-        else if (typeof amountRaw === "string" && amountRaw !== "") {
-            // The PG driver sometimes returns BIGINT as a string (when it exceeds the
-            // safe integer range of 2^53).
-            amountScaled = Number(amountRaw);
-            if (!Number.isSafeInteger(amountScaled)) {
-                throw new Error(`rehydrateMoney: field "${name}" amount string "${amountRaw}" is not a safe integer — DB corruption?`);
-            }
+        result[name] = readMoney(name, amountRaw, currencyRaw, fallbackCurrency);
+    }
+    return result;
+}
+/** One money value from its raw amount/currency columns; shared with SQL derived money so both
+ *  produce the identical read shape. Throws on a corrupt amount. */
+export function readMoney(name, amountRaw, currencyRaw, fallbackCurrency) {
+    let amountScaled;
+    if (typeof amountRaw === "number") {
+        amountScaled = amountRaw;
+    }
+    else if (typeof amountRaw === "bigint") {
+        amountScaled = Number(amountRaw);
+        if (!Number.isSafeInteger(amountScaled)) {
+            throw new Error(`rehydrateMoney: field "${name}" bigint amount is not a safe integer`);
         }
-        else {
-            throw new Error(`rehydrateMoney: field "${name}" amount has unexpected type ${typeof amountRaw}`);
+    }
+    else if (typeof amountRaw === "string" && amountRaw !== "") {
+        // The PG driver sometimes returns BIGINT as a string (when it exceeds the
+        // safe integer range of 2^53).
+        amountScaled = Number(amountRaw);
+        if (!Number.isSafeInteger(amountScaled)) {
+            throw new Error(`rehydrateMoney: field "${name}" amount string "${amountRaw}" is not a safe integer — DB corruption?`);
         }
-        const currency = typeof currencyRaw === "string" && currencyRaw !== "" ? currencyRaw : fallbackCurrency;
-        // amountMinor: deprecated alias, same value as amountScaled — see MoneyRead.
-        result[name] = {
-            amount: toMajorUnits(amountScaled),
-            currency,
-            amountScaled,
-            amountMinor: amountScaled,
-        };
     }
-    return result;
+    else {
+        throw new Error(`rehydrateMoney: field "${name}" amount has unexpected type ${typeof amountRaw}`);
+    }
+    const currency = typeof currencyRaw === "string" && currencyRaw !== "" ? currencyRaw : fallbackCurrency;
+    // amountMinor: deprecated alias, same value as amountScaled — see MoneyRead.
+    return {
+        amount: toMajorUnits(amountScaled),
+        currency,
+        amountScaled,
+        amountMinor: amountScaled,
+    };
 }

package/dist/db/parent-ref-clause.d.ts

@@ -8,4 +8,5 @@ export type { ParentVisibilityOption } from "@cosmicdrift/kumiko-types/event-sto
 export declare function buildParentRefClause(entity: EntityDefinition, table: Table, tableName: string, user: SessionUser, db: TenantDb, option: ParentVisibilityOption | undefined, opts: {
     readonly includeDeleted?: boolean;
     readonly narrowTypes?: ReadonlySet<string>;
+    readonly requireReadHandler?: boolean;
 }): OwnershipClause;