@cosmicdrift/kumiko-framework 0.398.0 → 0.400.0

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;

package/dist/db/parent-ref-clause.js

@@ -3,24 +3,28 @@ import { SYSTEM_TENANT_ID, UUID_SHAPE_PATTERN } from "../engine/types/identifier
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
 import { schemaTableName } from "./table-introspection.js";
 const candidateStaticsCache = new WeakMap();
-function candidateStaticsFor(candidateName, candidate) {
+function candidateStaticsFor(candidateName, candidate, resolveTable) {
+    if (resolveTable !== undefined)
+        return staticsOf(resolveTable(candidateName));
     const cached = candidateStaticsCache.get(candidate);
     if (cached)
         return cached;
-    const table = buildEntityTable(candidateName, candidate);
+    const statics = staticsOf(buildEntityTable(candidateName, candidate));
+    candidateStaticsCache.set(candidate, statics);
+    return statics;
+}
+function staticsOf(table) {
     const tableName = String(schemaTableName(table));
-    const statics = {
+    return {
         table,
         tableName,
         tenantIdCol: table["tenantId"] !== undefined ? physicalColumnName(table, "tenantId") : undefined,
         isDeletedCol: table["isDeleted"] !== undefined ? physicalColumnName(table, "isDeleted") : undefined,
     };
-    candidateStaticsCache.set(candidate, statics);
-    return statics;
 }
 // Candidate order follows `option.entities` (Registry insertion order) —
 // deterministic given a fixed feature-registration order.
-function selectCandidates(parentRef, option, narrowTypes) {
+function selectCandidates(parentRef, option, narrowTypes, requireReadHandler) {
     const candidates = [];
     for (const [name, candidate] of option.entities) {
         if (parentRef.allowedTypes && !parentRef.allowedTypes.includes(name))
@@ -31,6 +35,11 @@ function selectCandidates(parentRef, option, narrowTypes) {
         // need its own visibility resolved first, which this function doesn't do.
         if (candidate.parentRef !== undefined)
             continue;
+        // A readGate host would need its own gate resolved first; unreadable beats a widened read.
+        if (candidate.readGate !== undefined)
+            continue;
+        if (requireReadHandler && option.canReadEntity?.(name) !== true)
+            continue;
         // event-store-executor-context.ts rejects non-uuid idType at executor
         // build time, so there is no read path to check such a candidate against.
         if (candidate.idType !== undefined && candidate.idType !== "uuid")
@@ -58,7 +67,7 @@ export function buildParentRefClause(entity, table, tableName, user, db, option,
     }
     const typeCol = physicalColumnName(table, parentRef.entityTypeField);
     const idCol = physicalColumnName(table, parentRef.entityIdField);
-    const candidates = selectCandidates(parentRef, option, opts.narrowTypes);
+    const candidates = selectCandidates(parentRef, option, opts.narrowTypes, opts.requireReadHandler === true);
     if (candidates.length === 0)
         return { kind: "empty" };
     // The uuid shape and the tenant ids are bound once and shared by every
@@ -85,6 +94,7 @@ export function buildParentRefClause(entity, table, tableName, user, db, option,
             // kept, so a dropped branch reserves no index and can't shift the
             // positional binding of the branches after it.
             typeParamIdx: params.length + 1,
+            resolveTable: option.resolveTable,
         });
         if (branch === undefined)
             continue;
@@ -99,7 +109,7 @@ export function buildParentRefClause(entity, table, tableName, user, db, option,
 // read ownership can never match — an unsatisfiable arm is dropped rather than
 // emitted, which is what keeps an unreadable host from widening the OR-chain.
 function buildCandidateBranch(candidateName, candidate, user, ctx) {
-    const statics = candidateStaticsFor(candidateName, candidate);
+    const statics = candidateStaticsFor(candidateName, candidate, ctx.resolveTable);
     const ownership = buildOwnershipClause(user, candidate.access?.read, statics.table, ctx.typeParamIdx + 1);
     if (ownership.kind === "empty")
         return undefined;

package/dist/db/read-gate-clause.d.ts

@@ -0,0 +1,7 @@
+import type { ParentVisibilityOption } from "@cosmicdrift/kumiko-types/event-store-executor-types";
+import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
+import { type OwnershipClause } from "../engine/ownership.ts";
+import type { SessionUser } from "../engine/types/index.ts";
+import type { Table } from "./event-store-executor-context.ts";
+import type { TenantDb } from "./tenant-db.ts";
+export declare function buildReadGateClause(entity: EntityDefinition, table: Table, tableName: string, user: SessionUser, db: TenantDb, option: ParentVisibilityOption | undefined): OwnershipClause;

package/dist/db/read-gate-clause.js

@@ -0,0 +1,188 @@
+import { isFileField } from "../engine/field-helpers.js";
+import { buildOwnershipClause, combineClauses, normalizeAccessEntry, shiftParams, } from "../engine/ownership.js";
+import { SYSTEM_TENANT_ID, UUID_SHAPE_PATTERN } from "../engine/types/identifiers.js";
+import { FILE_REF_ENTITY_NAME } from "../files/types.js";
+import { isFrameworkSystemUser } from "./lock-guard.js";
+import { buildParentRefClause } from "./parent-ref-clause.js";
+import { buildEntityTable, physicalColumnName } from "./table-builder.js";
+import { schemaTableName } from "./table-introspection.js";
+const PASS = { kind: "pass" };
+const EMPTY = { kind: "empty" };
+const LINK_ALIAS = "gate_link";
+const FILE_ALIAS = "gate_file";
+// Placeholders are numbered from 1 per gate fragment; combineClauses shifts them into the
+// caller's statement, so every embedded fragment is shifted past the params collected so far.
+class GateSql {
+    params = [];
+    bind(value) {
+        this.params.push(value);
+        return `$${this.params.length}`;
+    }
+    embed(clause) {
+        const shifted = shiftParams({ sqlText: clause.sqlText, params: clause.params }, this.params.length);
+        this.params.push(...shifted.params);
+        return shifted.sqlText;
+    }
+}
+function tableOf(option, name, entity) {
+    return option.resolveTable?.(name) ?? buildEntityTable(name, entity);
+}
+function tenantScopeSql(sql, db, table, alias) {
+    if (table["tenantId"] === undefined || db.mode !== "tenant")
+        return [];
+    const first = sql.bind(db.tenantId);
+    const second = sql.bind(SYSTEM_TENANT_ID);
+    return [`"${alias}"."${physicalColumnName(table, "tenantId")}" IN (${first}, ${second})`];
+}
+function liveRowSql(entity, table, alias) {
+    if (entity.softDelete !== true || table["isDeleted"] === undefined)
+        return [];
+    return [`"${alias}"."${physicalColumnName(table, "isDeleted")}" = FALSE`];
+}
+function isRoleExempt(gate, user) {
+    return user.roles.some((role) => gate.linkExemptRoles?.includes(role) === true);
+}
+function anyLinkClause(input, link) {
+    const { option, user, db, tableName } = input;
+    const linkEntity = option.entities.get(link.entity);
+    if (linkEntity?.parentRef === undefined)
+        return EMPTY;
+    const linkTable = tableOf(option, link.entity, linkEntity);
+    const linkTableName = String(schemaTableName(linkTable));
+    const linkOwnership = combineClauses(buildOwnershipClause(user, linkEntity.access?.read, linkTable, 1, LINK_ALIAS), buildParentRefClause(linkEntity, linkTable, LINK_ALIAS, user, db, option, {
+        includeDeleted: false,
+        requireReadHandler: true,
+    }));
+    if (linkOwnership.kind === "empty")
+        return EMPTY;
+    const sql = new GateSql();
+    const conditions = [
+        `"${LINK_ALIAS}"."${physicalColumnName(linkTable, link.field)}"::text = "${tableName}"."${physicalColumnName(input.table, "id")}"::text`,
+        ...tenantScopeSql(sql, db, linkTable, LINK_ALIAS),
+        ...liveRowSql(linkEntity, linkTable, LINK_ALIAS),
+    ];
+    if (linkOwnership.kind === "sql")
+        conditions.push(sql.embed(linkOwnership));
+    return {
+        kind: "sql",
+        sqlText: `EXISTS (SELECT 1 FROM "${linkTableName}" AS "${LINK_ALIAS}" WHERE ${conditions.join(" AND ")})`,
+        params: sql.params,
+    };
+}
+// Every registered entity with a file field can own a file. Join rows and gated entities
+// are left out: their readability is not resolvable without recursion.
+function ownerCandidates(input, selfName) {
+    const { option } = input;
+    const owners = [];
+    for (const [name, entity] of option.entities) {
+        if (name === FILE_REF_ENTITY_NAME || name === selfName)
+            continue;
+        if (entity.parentRef !== undefined || entity.readGate !== undefined)
+            continue;
+        if (entity.idType !== undefined && entity.idType !== "uuid")
+            continue;
+        if (option.canReadEntity?.(name) !== true)
+            continue;
+        const fileFields = Object.entries(entity.fields)
+            .filter(([, field]) => isFileField(field))
+            .map(([fieldName]) => fieldName);
+        if (fileFields.length > 0)
+            owners.push({ name, entity, fileFields });
+    }
+    return owners;
+}
+function ownerBranch(input, owner, refTable, sql) {
+    const { option, user, db } = input;
+    const ownerTable = tableOf(option, owner.name, owner.entity);
+    const ownerTableName = String(schemaTableName(ownerTable));
+    const ownership = buildOwnershipClause(user, owner.entity.access?.read, ownerTable, 1, ownerTableName);
+    if (ownership.kind === "empty")
+        return undefined;
+    const readableAnywhere = [];
+    const fieldArms = [];
+    for (const field of owner.fileFields) {
+        const fieldRead = buildOwnershipClause(user, normalizeAccessEntry(owner.entity.fields[field]?.access?.read), ownerTable, 1, ownerTableName);
+        if (fieldRead.kind === "empty")
+            continue;
+        if (fieldRead.kind === "pass")
+            readableAnywhere.push(field);
+        else
+            fieldArms.push({ field, clause: fieldRead });
+    }
+    if (readableAnywhere.length === 0 && fieldArms.length === 0)
+        return undefined;
+    const typeSql = `"${FILE_ALIAS}"."${physicalColumnName(refTable, "entityType")}" = ${sql.bind(owner.name)}`;
+    const fieldCol = `"${FILE_ALIAS}"."${physicalColumnName(refTable, "fieldName")}"`;
+    const idCol = `"${FILE_ALIAS}"."${physicalColumnName(refTable, "entityId")}"`;
+    const uuidPattern = sql.bind(UUID_SHAPE_PATTERN);
+    const arms = [];
+    if (readableAnywhere.length > 0) {
+        arms.push(`${fieldCol} IN (${readableAnywhere.map((f) => sql.bind(f)).join(", ")})`);
+    }
+    for (const arm of fieldArms) {
+        if (arm.clause.kind !== "sql")
+            continue;
+        arms.push(`(${fieldCol} = ${sql.bind(arm.field)} AND ${sql.embed(arm.clause)})`);
+    }
+    const conditions = [
+        `"${ownerTableName}"."${physicalColumnName(ownerTable, "id")}" = (CASE WHEN ${idCol} ~ ${uuidPattern} THEN ${idCol} END)::uuid`,
+        ...tenantScopeSql(sql, db, ownerTable, ownerTableName),
+        ...liveRowSql(owner.entity, ownerTable, ownerTableName),
+    ];
+    if (ownership.kind === "sql")
+        conditions.push(sql.embed(ownership));
+    conditions.push(`(${arms.join(" OR ")})`);
+    return `(${typeSql} AND EXISTS (SELECT 1 FROM "${ownerTableName}" WHERE ${conditions.join(" AND ")}))`;
+}
+function fileOwnerClause(input, field) {
+    const { option, db, tableName, table, entity } = input;
+    const refEntity = option.entities.get(FILE_REF_ENTITY_NAME);
+    if (refEntity === undefined)
+        return EMPTY;
+    const refTable = tableOf(option, FILE_REF_ENTITY_NAME, refEntity);
+    const refTableName = String(schemaTableName(refTable));
+    // The registry holds a spread copy of the entity, so the table name is the stable identity.
+    const selfName = [...option.entities].find(([, candidate]) => candidate.table === entity.table)?.[0];
+    const sql = new GateSql();
+    const branches = [];
+    if (selfName !== undefined) {
+        const selfType = sql.bind(selfName);
+        branches.push(`("${FILE_ALIAS}"."${physicalColumnName(refTable, "entityType")}" = ${selfType} AND "${FILE_ALIAS}"."${physicalColumnName(refTable, "entityId")}" = "${tableName}"."${physicalColumnName(table, "id")}"::text)`);
+    }
+    for (const owner of ownerCandidates(input, selfName)) {
+        const branch = ownerBranch(input, owner, refTable, sql);
+        if (branch !== undefined)
+            branches.push(branch);
+    }
+    if (branches.length === 0)
+        return EMPTY;
+    const conditions = [
+        `"${FILE_ALIAS}"."${physicalColumnName(refTable, "id")}" = "${tableName}"."${physicalColumnName(table, field)}"`,
+        ...tenantScopeSql(sql, db, refTable, FILE_ALIAS),
+        ...liveRowSql(refEntity, refTable, FILE_ALIAS),
+        `(${branches.join(" OR ")})`,
+    ];
+    return {
+        kind: "sql",
+        sqlText: `EXISTS (SELECT 1 FROM "${refTableName}" AS "${FILE_ALIAS}" WHERE ${conditions.join(" AND ")})`,
+        params: sql.params,
+    };
+}
+// Without the registry the gate cannot be resolved; every caller but the framework system user
+// is denied, which is what forces hand-written handlers to wire parentVisibility.
+export function buildReadGateClause(entity, table, tableName, user, db, option) {
+    const gate = entity.readGate;
+    if (gate === undefined || isFrameworkSystemUser(user))
+        return PASS;
+    if (option === undefined)
+        return EMPTY;
+    const input = { entity, table, tableName, user, db, option };
+    let clause = PASS;
+    if (gate.anyLink !== undefined && !isRoleExempt(gate, user)) {
+        clause = combineClauses(clause, anyLinkClause(input, gate.anyLink));
+    }
+    if (gate.fileOwner !== undefined) {
+        clause = combineClauses(clause, fileOwnerClause(input, gate.fileOwner.field));
+    }
+    return clause;
+}

package/dist/db/read-ownership.d.ts

@@ -0,0 +1,9 @@
+import { type OwnershipClause } from "../engine/ownership.ts";
+import type { SessionUser } from "../engine/types/index.ts";
+import type { ExecutorContext } from "./event-store-executor-context.ts";
+import { type ParentVisibilityOption } from "./parent-ref-clause.ts";
+import type { TenantDb } from "./tenant-db.ts";
+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;

package/dist/db/read-ownership.js

@@ -0,0 +1,12 @@
+import { buildOwnershipClause, combineClauses } from "../engine/ownership.js";
+import { buildParentRefClause } from "./parent-ref-clause.js";
+import { buildReadGateClause } from "./read-gate-clause.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) and the declarative readGate (db/read-gate-clause.ts). `empty` means there's no row the user could ever see.
+// Lives apart from the list WHERE builder so the reference search and sort can gate their
+// target rows the same way without an import cycle.
+export function resolveReadOwnership(ctx, tableName, user, db, parentVisibility, gate) {
+    const parentClause = buildParentRefClause(ctx.entity, ctx.table, tableName, user, db, parentVisibility, gate);
+    return combineClauses(combineClauses(buildOwnershipClause(user, ctx.entity.access?.read, ctx.table, 1, tableName), parentClause), buildReadGateClause(ctx.entity, ctx.table, tableName, user, db, parentVisibility));
+}

package/dist/engine/boot-validator/boot-check.d.ts

@@ -1,2 +1,4 @@
 import type { FeatureDefinition } from "../types/index.ts";
-export declare function validateFeatureBootChecks(features: readonly FeatureDefinition[]): void;
+type FeatureBootCheck = FeatureDefinition["bootChecks"][number];
+export declare function runFeatureBootCheck(feature: FeatureDefinition, check: FeatureBootCheck, features: readonly FeatureDefinition[]): void;
+export {};

package/dist/engine/boot-validator/boot-check.js

@@ -4,17 +4,13 @@
 // the full mounted-feature set and throws to fail the boot; we wrap the
 // message with the owning feature's name so the error text points back at
 // the feature that declared the check.
-export function validateFeatureBootChecks(features) {
+export function runFeatureBootCheck(feature, check, features) {
     const ctx = { features };
-    for (const feature of features) {
-        for (const check of feature.bootChecks) {
-            try {
-                check(ctx);
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}`);
-            }
-        }
+    try {
+        check(ctx);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}`);
     }
 }

package/dist/engine/boot-validator/boot-context.d.ts

@@ -0,0 +1,26 @@
+import type { ConfigKeyDefinition } from "@cosmicdrift/kumiko-types/config";
+import type { FeatureDefinition } from "../types/index.ts";
+import type { ValidateBootOptions } from "./boot-options.ts";
+import { collectKnownRoles, collectNavQns, collectWriteHandlerQns } from "./nav.ts";
+import { collectClaimKeys } from "./ownership.ts";
+import { buildQueryHandlerMap } from "./projection-list-screens.ts";
+import { collectScreenQns, collectScreensByShortId } from "./screens.ts";
+import { collectWorkspaceQns } from "./workspaces.ts";
+export type BootContext = {
+    readonly features: readonly FeatureDefinition[];
+    readonly featureMap: ReadonlyMap<string, FeatureDefinition>;
+    readonly options: ValidateBootOptions | undefined;
+    readonly extensionProviders: ReadonlyMap<string, string>;
+    readonly allConfigKeys: ReadonlySet<string>;
+    readonly configKeyDefsByQn: ReadonlyMap<string, ConfigKeyDefinition>;
+    readonly allClaimKeys: ReturnType<typeof collectClaimKeys>;
+    readonly knownRoles: ReturnType<typeof collectKnownRoles>;
+    readonly allScreenQns: ReturnType<typeof collectScreenQns>;
+    readonly allNavQns: ReturnType<typeof collectNavQns>;
+    readonly allWorkspaceQns: ReturnType<typeof collectWorkspaceQns>;
+    readonly allWriteHandlerQns: ReturnType<typeof collectWriteHandlerQns>;
+    readonly screensByShortId: ReturnType<typeof collectScreensByShortId>;
+    readonly queryHandlerQns: ReturnType<typeof buildQueryHandlerMap>;
+};
+export declare function buildBootContext(features: readonly FeatureDefinition[], options: ValidateBootOptions | undefined): BootContext;
+export declare function collectExposedApis(features: readonly FeatureDefinition[]): Map<string, string>;

package/dist/engine/boot-validator/boot-context.js

@@ -0,0 +1,57 @@
+import { QnTypes, qualifyEntityName } from "../qualified-name.js";
+import { collectKnownRoles, collectNavQns, collectWriteHandlerQns } from "./nav.js";
+import { collectClaimKeys } from "./ownership.js";
+import { buildQueryHandlerMap } from "./projection-list-screens.js";
+import { collectScreenQns, collectScreensByShortId } from "./screens.js";
+import { collectWorkspaceQns } from "./workspaces.js";
+export function buildBootContext(features, options) {
+    const featureMap = new Map();
+    const extensionProviders = new Map();
+    const allConfigKeys = new Set();
+    // The raw f.configKeys key is the camelCase object key; the QN is built by
+    // define-feature/registry via qualifyEntityName (kebab-cased), so configEdit
+    // screens with multi-word keys only resolve against the qualified form.
+    // allConfigKeys keeps the older `feature.key` form for validateConfigReads.
+    const configKeyDefsByQn = new Map();
+    for (const f of features) {
+        featureMap.set(f.name, f);
+        for (const extName of Object.keys(f.registrarExtensions)) {
+            extensionProviders.set(extName, f.name);
+        }
+        for (const [key, def] of Object.entries(f.configKeys)) {
+            allConfigKeys.add(`${f.name}.${key}`);
+            configKeyDefsByQn.set(qualifyEntityName(f.name, QnTypes.config, key), def);
+        }
+    }
+    return {
+        features,
+        featureMap,
+        options,
+        extensionProviders,
+        allConfigKeys,
+        configKeyDefsByQn,
+        allClaimKeys: collectClaimKeys(features),
+        // Corpus of "referenced in any handler access rule" (there is no runtime
+        // role registry), so typos like "Admi" fail at boot.
+        knownRoles: collectKnownRoles(features),
+        allScreenQns: collectScreenQns(features),
+        allNavQns: collectNavQns(features),
+        allWorkspaceQns: collectWorkspaceQns(features),
+        allWriteHandlerQns: collectWriteHandlerQns(features),
+        screensByShortId: collectScreensByShortId(features),
+        queryHandlerQns: buildQueryHandlerMap(features),
+    };
+}
+export function collectExposedApis(features) {
+    const allExposedApis = new Map(); // apiName → providerFeature
+    for (const f of features) {
+        for (const apiName of f.exposedApis) {
+            const existing = allExposedApis.get(apiName);
+            if (existing && existing !== f.name) {
+                throw new Error(`Cross-feature API "${apiName}" exposed by both "${existing}" and "${f.name}" — API names must be globally unique.`);
+            }
+            allExposedApis.set(apiName, f.name);
+        }
+    }
+    return allExposedApis;
+}