@cosmicdrift/kumiko-framework 0.399.0 → 0.400.0

package/dist/files/dispose-removed-file-refs.js

@@ -1,7 +1,6 @@
-import { isFileField } from "../engine/field-helpers.js";
 import { reraiseAsKumikoError } from "../errors/index.js";
-import { fileRefIdsOf } from "./bind-pending-file-refs.js";
 import { getFileRefExecutor } from "./create-file-ref.js";
+import { fileRefIdsInField, holdsFileRefs } from "./file-field-slots.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
 // The bound fieldName may differ from the field the id was removed from: an id
 // moved A -> B stays bound to A (binding never re-targets).
@@ -10,15 +9,13 @@ function isBoundToRecord(row, entityName, entityId, fileFields) {
     return (row["entityType"] === entityName &&
         row["entityId"] === entityId &&
         typeof boundField === "string" &&
-        isFileField(fileFields[boundField]));
+        holdsFileRefs(fileFields[boundField]));
 }
 // Across all file fields: an id moved from one field to another is still in use.
 function fileRefIdsStoredInAnyField(fields, data) {
     const ids = new Set();
     for (const [fieldName, fieldDef] of Object.entries(fields)) {
-        if (!isFileField(fieldDef))
-            continue;
-        for (const fileRefId of fileRefIdsOf(data[fieldName]))
+        for (const fileRefId of fileRefIdsInField(fieldDef, data[fieldName]))
             ids.add(fileRefId);
     }
     return ids;
@@ -50,9 +47,9 @@ export async function disposeRemovedFileRefs(args) {
     const executor = getFileRefExecutor();
     const keptAnywhere = fileRefIdsStoredInAnyField(entity.fields, result.data);
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
-        if (!isFileField(fieldDef) || !(fieldName in result.changes))
+        if (!holdsFileRefs(fieldDef) || !(fieldName in result.changes))
             continue;
-        for (const fileRefId of fileRefIdsOf(result.previous[fieldName])) {
+        for (const fileRefId of fileRefIdsInField(fieldDef, result.previous[fieldName])) {
             if (keptAnywhere.has(fileRefId))
                 continue;
             const row = await executor.detail({ id: fileRefId }, user, db);

package/dist/files/file-field-slots.d.ts

@@ -0,0 +1,10 @@
+import type { EmbeddedFileSubFieldDef, EmbeddedSubFieldDef, FieldDefinition } from "../engine/types/fields.ts";
+export declare function fileRefIdsOf(value: unknown): readonly string[];
+export declare function isFileSubField(sub: EmbeddedSubFieldDef): sub is EmbeddedFileSubFieldDef;
+/** A field whose value carries FileRef ids: a file field itself, or an embedded field with file sub-fields. */
+export declare function holdsFileRefs(def: FieldDefinition | undefined): boolean;
+/** FileRef ids a field value names. `file_refs.fieldName` stays the top-level field, never the sub-field. */
+export declare function fileRefIdsInField(def: FieldDefinition | undefined, value: unknown): string[];
+/** FileRef ids per file sub-field of an embedded field value, pooled over all rows. */
+export declare function fileRefIdsBySubField(def: FieldDefinition | undefined, value: unknown): ReadonlyMap<string, readonly string[]>;
+export declare function resolveFileSubField(def: FieldDefinition | undefined, subField: string): EmbeddedFileSubFieldDef | undefined;

package/dist/files/file-field-slots.js

@@ -0,0 +1,53 @@
+import { isUuid } from "@cosmicdrift/kumiko-types/identifiers";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { isFileField } from "../engine/field-helpers.js";
+export function fileRefIdsOf(value) {
+    if (typeof value === "string")
+        return isUuid(value) ? [value] : [];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string" && isUuid(item));
+}
+export function isFileSubField(sub) {
+    return sub.type === "images" || sub.type === "files";
+}
+function fileSubFieldNames(def) {
+    return Object.entries(def.schema).flatMap(([name, sub]) => (isFileSubField(sub) ? [name] : []));
+}
+/** A field whose value carries FileRef ids: a file field itself, or an embedded field with file sub-fields. */
+export function holdsFileRefs(def) {
+    if (def === undefined)
+        return false;
+    if (isFileField(def))
+        return true;
+    return def.type === "embedded" && Object.values(def.schema).some(isFileSubField);
+}
+/** FileRef ids a field value names. `file_refs.fieldName` stays the top-level field, never the sub-field. */
+export function fileRefIdsInField(def, value) {
+    if (def === undefined)
+        return [];
+    if (isFileField(def))
+        return [...fileRefIdsOf(value)];
+    if (def.type !== "embedded")
+        return [];
+    const subNames = fileSubFieldNames(def);
+    const rows = Array.isArray(value) ? value : [value];
+    return rows.flatMap((row) => isPlainObject(row) ? subNames.flatMap((name) => fileRefIdsOf(row[name])) : []);
+}
+/** FileRef ids per file sub-field of an embedded field value, pooled over all rows. */
+export function fileRefIdsBySubField(def, value) {
+    const bySubField = new Map();
+    if (def?.type !== "embedded")
+        return bySubField;
+    const rows = Array.isArray(value) ? value : [value];
+    for (const name of fileSubFieldNames(def)) {
+        bySubField.set(name, rows.flatMap((row) => (isPlainObject(row) ? fileRefIdsOf(row[name]) : [])));
+    }
+    return bySubField;
+}
+export function resolveFileSubField(def, subField) {
+    if (def?.type !== "embedded")
+        return undefined;
+    const sub = def.schema[subField];
+    return sub !== undefined && isFileSubField(sub) ? sub : undefined;
+}

package/dist/files/file-ref-entity.d.ts

@@ -19,7 +19,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly sensitive?: boolean;
         readonly default?: number;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
     };
     readonly entityType: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {

package/dist/files/file-ref-table.d.ts

@@ -18,7 +18,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
         readonly sensitive?: boolean;
         readonly default?: number;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
     };
     readonly entityType: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {

package/dist/files/file-routes.js

@@ -17,6 +17,7 @@ import { listActionFormFileFields, mayUseActionForm } from "./action-form-upload
 import { buildContentDispositionHeader } from "./content-disposition.js";
 import { DEFAULT_MAX_UPLOAD_SIZE, getFileRefExecutor, storeFileAsFileRef, } from "./create-file-ref.js";
 import { createDefaultGuard, DEFAULT_PRIVILEGED_ROLES } from "./default-file-guard.js";
+import { isFileSubField } from "./file-field-slots.js";
 import { createFileContext, createTenantFileContext } from "./file-handle.js";
 import { fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
@@ -48,6 +49,12 @@ const BATCH_META_CONCURRENCY = 10;
 // Multipart framing plus the small entityType/entityId/fieldName parts
 // riding alongside the file.
 const MULTIPART_OVERHEAD_MARGIN_BYTES = 64 * 1024;
+function fileFieldMaxSizes(field) {
+    if (field.type === "embedded") {
+        return Object.values(field.schema).flatMap((sub) => isFileSubField(sub) && sub.maxSize ? [sub.maxSize] : []);
+    }
+    return isFileField(field) && field.maxSize ? [field.maxSize] : [];
+}
 // entityType/fieldName (and therefore the field's own maxSize) are only
 // known after the body is parsed, so this covers the largest configured
 // field, not just the global default.
@@ -55,8 +62,8 @@ export function resolveMaxUploadBodyBytes(options) {
     let maxBytes = parseMaxSize(options.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE);
     for (const entity of options.registry?.getAllEntities().values() ?? []) {
         for (const field of Object.values(entity.fields)) {
-            if (isFileField(field) && field.maxSize) {
-                maxBytes = Math.max(maxBytes, parseMaxSize(field.maxSize));
+            for (const maxSize of fileFieldMaxSizes(field)) {
+                maxBytes = Math.max(maxBytes, parseMaxSize(maxSize));
             }
         }
     }
@@ -162,6 +169,7 @@ export function createFileRoutes(options) {
         // store it in the text entityId column.
         const entityId = typeof body["entityId"] === "string" ? body["entityId"] : undefined;
         const fieldName = typeof body["fieldName"] === "string" ? body["fieldName"] : undefined;
+        const subField = typeof body["subField"] === "string" ? body["subField"] : undefined;
         const actionForm = typeof body["actionForm"] === "string" ? body["actionForm"] : undefined;
         if (isAnonymous &&
             !isAnonymousPendingUploadAllowed(options.registry, {
@@ -197,7 +205,7 @@ export function createFileRoutes(options) {
             const decision = options.registry !== undefined && options.registry.getEntity(entityType) === undefined
                 ? RecordWriteDecisions.writable
                 : options.canWriteRecord
-                    ? await options.canWriteRecord({ entityType, entityId, fieldName, user })
+                    ? await options.canWriteRecord({ entityType, entityId, fieldName, subField, user })
                     : RecordWriteDecisions.forbidden;
             switch (decision) {
                 case RecordWriteDecisions.writable:
@@ -235,6 +243,7 @@ export function createFileRoutes(options) {
             entityType,
             entityId,
             fieldName,
+            subField,
             actionForm,
         });
         if (outcome.kind === "rejected")

package/dist/files/index.d.ts

@@ -8,6 +8,7 @@ export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytes
 export { createDefaultGuard } from "./default-file-guard.ts";
 export { deleteFileRefsBoundToRecord } from "./delete-record-file-refs.ts";
 export { createFilesFeature, FILES_FEATURE } from "./feature.ts";
+export { holdsFileRefs } from "./file-field-slots.ts";
 export type { FileContext } from "./file-handle.ts";
 export { createFileContext, createTenantFileContext, deriveKey, storageKeyStemPrefix, } from "./file-handle.ts";
 export { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.ts";

package/dist/files/index.js

@@ -5,6 +5,7 @@ export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytes
 export { createDefaultGuard } from "./default-file-guard.js";
 export { deleteFileRefsBoundToRecord } from "./delete-record-file-refs.js";
 export { createFilesFeature, FILES_FEATURE } from "./feature.js";
+export { holdsFileRefs } from "./file-field-slots.js";
 // `createFileHandle` is an implementation detail — construct handles via
 // `createFileContext(provider).ref(key)`, which is the AppContext surface.
 export { createFileContext, createTenantFileContext, deriveKey, storageKeyStemPrefix, } from "./file-handle.js";

package/dist/files/load-save-file-refs.js

@@ -1,8 +1,7 @@
 import { selectMany } from "../db/query.js";
 import { tenantDbRunner } from "../db/tenant-db-runner.js";
-import { isFileField } from "../engine/field-helpers.js";
 import { getStreamVersions } from "../event-store/event-store.js";
-import { fileRefIdsOf } from "./bind-pending-file-refs.js";
+import { fileRefIdsInField, holdsFileRefs } from "./file-field-slots.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
 // One query for every fileRef a save names, restricted to the writer's own tenant and live
@@ -19,9 +18,9 @@ export async function loadSaveFileRefs(args) {
         return new Map();
     const ids = new Set();
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
-        if (!isFileField(fieldDef))
+        if (!holdsFileRefs(fieldDef))
             continue;
-        for (const id of fileRefIdsOf(result.changes[fieldName]))
+        for (const id of fileRefIdsInField(fieldDef, result.changes[fieldName]))
             ids.add(id);
     }
     return loadFileRefRows(db, [...ids], user.tenantId);

package/dist/files/record-read-check.js

@@ -1,35 +1,7 @@
-import { toKebab } from "../engine/qualified-name.js";
+import { collectEntityDetailQueries } from "../api/entity-read-access.js";
 import { isKumikoError } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/index.js";
 const log = createFallbackLogger("files");
-// Only the "<entity>:detail" handler counts: other "<entity>:...:detail"
-// queries map to the same entity but may return a different shape or scope.
-// Entity names are globally unique and only the owning feature maps handlers
-// to its entity, so at most one QN matches per entity.
-function isEntityDetailQuery(qn, entityName) {
-    return qn.endsWith(`:query:${toKebab(entityName)}:detail`);
-}
-function buildDetailQueryIndex(registry) {
-    const detailQueryByEntity = new Map();
-    for (const qn of registry.getAllQueryHandlers().keys()) {
-        const entityName = registry.getHandlerEntity(qn);
-        if (entityName !== undefined && isEntityDetailQuery(qn, entityName)) {
-            detailQueryByEntity.set(entityName, qn);
-        }
-    }
-    for (const projection of registry.getAllProjections().values()) {
-        const entityName = projection.source;
-        if (typeof entityName !== "string")
-            continue;
-        const owner = registry.getReadModelEntityOwner(entityName);
-        if (owner === undefined)
-            continue;
-        const qn = `${owner}:query:${toKebab(entityName)}:detail`;
-        if (registry.getAllQueryHandlers().has(qn))
-            detailQueryByEntity.set(entityName, qn);
-    }
-    return detailQueryByEntity;
-}
 // "May this user read the record?" is answered by the entity's own detail
 // query run as that user: handler access, row ownership and parent visibility
 // all apply, exactly as when the record is opened. null (not found or not
@@ -38,7 +10,7 @@ function buildDetailQueryIndex(registry) {
 export function createRecordReadCheck(registry, query) {
     let detailQueryByEntity;
     return async ({ entityType, entityId, user }) => {
-        detailQueryByEntity ??= buildDetailQueryIndex(registry);
+        detailQueryByEntity ??= collectEntityDetailQueries(registry);
         const detailQuery = detailQueryByEntity.get(entityType);
         if (detailQuery === undefined)
             return false;

package/dist/files/record-write-check.d.ts

@@ -12,6 +12,8 @@ export type RecordWriteCheck = (args: {
     readonly entityType: string;
     readonly entityId: string;
     readonly fieldName: string | undefined;
+    /** Embedded file sub-field of `fieldName` the upload is meant for. */
+    readonly subField?: string | undefined;
     readonly user: SessionUser;
 }) => Promise<RecordWriteDecision>;
 export declare function findImplicitEntityTable(registry: Registry, entityType: string): import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable | undefined;

package/dist/files/record-write-check.js

@@ -1,7 +1,9 @@
 import { hasAccess } from "../engine/access.js";
+import { userHasWriteRole } from "../engine/field-access.js";
 import { normalizeAccessEntry, userCanWriteFieldRow } from "../engine/ownership.js";
 import { toKebab } from "../engine/qualified-name.js";
 import { isRecordLocked } from "../engine/screen-helpers.js";
+import { resolveFileSubField } from "./file-field-slots.js";
 export const RecordWriteDecisions = {
     writable: "writable",
     notFound: "not_found",
@@ -19,6 +21,20 @@ export function findImplicitEntityTable(registry, entityType) {
 function isEntityUpdateWrite(qn, entityName) {
     return qn.endsWith(`:write:${toKebab(entityName)}:update`);
 }
+// The named field's own write rules against the stored row. The upload names no embedded row,
+// so a sub-field only gets the role gate; its row-level rules run when the record is saved.
+function mayWriteNamedField(args) {
+    const { entity, fieldName, subField, user, row } = args;
+    if (fieldName === undefined)
+        return true;
+    const fieldRules = normalizeAccessEntry(entity.fields[fieldName]?.access?.write);
+    if (!userCanWriteFieldRow(user, fieldRules, row, row))
+        return false;
+    const subFieldRules = subField === undefined
+        ? undefined
+        : normalizeAccessEntry(resolveFileSubField(entity.fields[fieldName], subField)?.access?.write);
+    return subFieldRules === undefined || userHasWriteRole(user, subFieldRules);
+}
 // "May this user attach a file to the record?" asks what saving the record would ask: the
 // entity's update handler, the row-level and field-level write rules against the stored row,
 // and the lock. Not-readable, foreign-tenant and missing records answer alike (not_found) so
@@ -33,7 +49,7 @@ export function createRecordWriteCheck(args) {
         }
         return undefined;
     }
-    return async ({ entityType, entityId, fieldName, user }) => {
+    return async ({ entityType, entityId, fieldName, subField, user }) => {
         if (!(await canReadRecord({ entityType, entityId, user }))) {
             return RecordWriteDecisions.notFound;
         }
@@ -53,8 +69,7 @@ export function createRecordWriteCheck(args) {
         if (!userCanWriteFieldRow(user, entity.access?.write, row, row)) {
             return RecordWriteDecisions.forbidden;
         }
-        const fieldWriteRules = fieldName === undefined ? undefined : entity.fields[fieldName]?.access?.write;
-        if (!userCanWriteFieldRow(user, normalizeAccessEntry(fieldWriteRules), row, row)) {
+        if (!mayWriteNamedField({ entity, fieldName, subField, user, row })) {
             return RecordWriteDecisions.forbidden;
         }
         if (isRecordLocked(entity.lockedWhen, row))

package/dist/files/upload-field-resolution.d.ts

@@ -4,6 +4,7 @@ type UploadTarget = {
     readonly entityType?: string | undefined;
     readonly entityId?: string | undefined;
     readonly fieldName?: string | undefined;
+    readonly subField?: string | undefined;
     readonly actionForm?: string | undefined;
 };
 export type AttachTargets = "entities" | "entities-and-read-models";
@@ -15,7 +16,7 @@ type AttachedFieldResolution = {
 } | {
     readonly kind: "unresolvable";
 };
-export declare function resolveAttachedField(registry: Registry | undefined, entityType: string | undefined, fieldName: string | undefined, attachTargets?: AttachTargets): AttachedFieldResolution;
+export declare function resolveAttachedField(registry: Registry | undefined, entityType: string | undefined, fieldName: string | undefined, attachTargets?: AttachTargets, subField?: string): AttachedFieldResolution;
 type UploadFieldResolution = AttachedFieldResolution | {
     readonly kind: "rejected";
     readonly error: string;

package/dist/files/upload-field-resolution.js

@@ -1,30 +1,48 @@
 import { isFileField } from "../engine/field-helpers.js";
 import { isActionFormScreenQn, resolveActionFormFileField } from "./action-form-upload.js";
+import { resolveFileSubField } from "./file-field-slots.js";
+function findAttachEntity(registry, entityType, attachTargets) {
+    return (registry?.getEntity(entityType) ??
+        (attachTargets === "entities-and-read-models"
+            ? registry?.getReadModelEntity(entityType)
+            : undefined));
+}
 // entityType/fieldName drive the GDPR-forget decision downstream
 // (fileRefDeleteHook resolves the field's PII annotation from exactly this
 // pairing) — attaching to a field nobody can resolve would leave that
-// decision hanging on an unverified client string. Either both are omitted
+// decision hanging on an unverified client string. `subField` names a file sub-field of an
+// embedded `fieldName`; the binding stays on the top-level field. Either both are omitted
 // (unattached upload, allowed) or both must resolve to a real registered
 // field. "entities-and-read-models" is for server-side callers only: a client upload must
 // never name a projection entity, whose rows nobody can write-check.
-export function resolveAttachedField(registry, entityType, fieldName, attachTargets = "entities") {
+export function resolveAttachedField(registry, entityType, fieldName, attachTargets = "entities", subField) {
     if (entityType === undefined && fieldName === undefined)
         return { kind: "unattached" };
-    const entity = entityType !== undefined
-        ? (registry?.getEntity(entityType) ??
-            (attachTargets === "entities-and-read-models"
-                ? registry?.getReadModelEntity(entityType)
-                : undefined))
-        : undefined;
-    const fieldDef = entity && fieldName !== undefined ? entity.fields[fieldName] : undefined;
-    if (!entityType || !fieldName || !entity || !fieldDef || !isFileField(fieldDef))
+    if (!entityType || !fieldName)
+        return { kind: "unresolvable" };
+    const fieldDef = findAttachEntity(registry, entityType, attachTargets)?.fields[fieldName];
+    if (!fieldDef)
+        return { kind: "unresolvable" };
+    if (subField !== undefined) {
+        const subFieldDef = resolveFileSubField(fieldDef, subField);
+        return subFieldDef === undefined
+            ? { kind: "unresolvable" }
+            : { kind: "resolved", fieldDef: subFieldDef };
+    }
+    if (!isFileField(fieldDef))
         return { kind: "unresolvable" };
     return { kind: "resolved", fieldDef };
 }
 export function resolveUploadField(registry, input, attachTargets) {
-    const { entityType, entityId, fieldName, actionForm } = input;
+    const { entityType, entityId, fieldName, subField, actionForm } = input;
     if (actionForm === undefined) {
-        return resolveAttachedField(registry, entityType, fieldName, attachTargets);
+        return resolveAttachedField(registry, entityType, fieldName, attachTargets, subField);
+    }
+    if (subField !== undefined) {
+        return {
+            kind: "rejected",
+            error: "invalid_action_form: actionForm cannot be combined with subField",
+        };
     }
     if (entityType !== undefined || entityId !== undefined) {
         return {
@@ -72,5 +90,7 @@ export function isAnonymousPendingUploadAllowed(registry, target) {
     if (target.entityId !== undefined || target.actionForm !== undefined)
         return false;
     const resolution = resolveAttachedField(registry, target.entityType, target.fieldName);
-    return resolution.kind === "resolved" && resolution.fieldDef.anonymousUpload === true;
+    return (resolution.kind === "resolved" &&
+        isFileField(resolution.fieldDef) &&
+        resolution.fieldDef.anonymousUpload === true);
 }

package/dist/pipeline/dispatch-batch.js

@@ -176,12 +176,13 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
             for (const r of results) {
                 if (!r.isSuccess)
                     continue;
-                if (!isLifecycleResult(r.data))
+                const lifecycleResult = r.lifecycle ?? r.data;
+                if (!isLifecycleResult(lifecycleResult))
                     continue;
-                if (r.data.kind === "save")
-                    saves.push(r.data);
-                else if (r.data.kind === "delete")
-                    deletes.push(r.data);
+                if (lifecycleResult.kind === "save")
+                    saves.push(lifecycleResult);
+                else if (lifecycleResult.kind === "delete")
+                    deletes.push(lifecycleResult);
             }
             // skip: nothing to flush when there are no lifecycle hooks or no successful save/delete
             if (!lifecycle || (saves.length === 0 && deletes.length === 0))

package/dist/pipeline/dispatch-write.js

@@ -508,7 +508,7 @@ async function invokeWriteHandler(handler, type, gated, user, handlerContext) {
 async function runWriteLifecycle(ctx, args) {
     try {
         const runner = resolveDbSource(ctx, args.tx);
-        await runLifecycle(ctx, args.type, args.result.data, args.handlerContext, args.user, args.origin, args.afterCommitHooks, runner);
+        await runLifecycle(ctx, args.type, args.result.lifecycle ?? args.result.data, args.handlerContext, args.user, args.origin, args.afterCommitHooks, runner);
     }
     catch (e) {
         return writeFailure(wrapToKumiko(e));
@@ -584,5 +584,6 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
     // data / previous / changes). Feature code that fed a plaintext through
     // to the return payload fails here instead of hitting the client.
     assertNoSecretLeak(result.data);
+    assertNoSecretLeak(result.lifecycle);
     return result;
 }

package/dist/pipeline/write-result-masking.js

@@ -25,10 +25,11 @@ function maskLifecycleOrRow(entity, data) {
 export function maskWriteResultForClient(registry, handlerType, result) {
     if (!result.isSuccess)
         return result;
+    const { lifecycle, ...clientResult } = result;
     const entityName = registry.getHandlerEntity(handlerType);
     const entity = entityName ? registry.getEntity(entityName) : undefined;
     const data = maskLifecycleOrRow(entity, result.data);
-    return data === result.data ? result : { ...result, data };
+    return data === result.data && lifecycle === undefined ? result : { ...clientResult, data };
 }
 export function maskBatchResultForClient(registry, commands, batch) {
     const results = batch.results.map((result, index) => {

package/dist/schema-cli/validate-command.js

@@ -4,6 +4,7 @@ import { assertRowLevelSecurityTableState, createDbConnection, generateMigration
 import { isLiveFrameworkTable } from "../db/known-table-names.js";
 import { readMigrationSqlTexts } from "../db/migrate-runner.js";
 import { diffReplayAgainstSnapshot, replayMigrationsDir } from "../db/replay-migration-sql.js";
+import { BootValidationError } from "../engine/boot-validator/boot-rule.js";
 import { validateBoot } from "../engine/boot-validator.js";
 import { describeThrown, loadPreviousSnapshot, loadSchemaModOrReport, nextSequenceNumber, SNAPSHOT_FILENAME, } from "./shared.js";
 import { featureDefinitionsOf, parseValidateBootOptions, withFileStoragePresence, } from "./validate-boot-input.js";
@@ -35,6 +36,16 @@ function checkSchemaDrift(ctx, schemaMod, prevSnapshot) {
     out.err("    Fix: `kumiko-schema generate <name>`, then commit the migration.");
     return false;
 }
+function unclassifiedViolation(check, e) {
+    return { ruleId: `unclassified/${check}`, check, message: describeThrown(e) };
+}
+function reportBootViolations(out, violations) {
+    for (const v of violations) {
+        out.err(`  ✗ boot [${v.ruleId}] ${v.message}`);
+        if (v.fix !== undefined)
+            out.err(`    Fix: ${v.fix}`);
+    }
+}
 // 2. Boot validity — needs the composed feature set.
 function checkBootValidity(out, schemaMod) {
     let bootFeatures;
@@ -43,11 +54,11 @@ function checkBootValidity(out, schemaMod) {
     }
     catch (e) {
         out.err(`  ✗ boot: ${describeThrown(e)}`);
-        return false;
+        return { ok: false, violations: [unclassifiedViolation("featureDefinitionsOf", e)] };
     }
     if (bootFeatures === undefined) {
         out.log("  · boot: skipped — add `export const FEATURES = composeFeatures(APP_FEATURES, { includeBundled: true })` to kumiko/schema.ts to enable validateBoot.");
-        return true;
+        return { ok: true, skipped: true, violations: [] };
     }
     try {
         validateBoot(bootFeatures, {
@@ -55,11 +66,15 @@ function checkBootValidity(out, schemaMod) {
             env: withFileStoragePresence(process.env),
         });
         out.log("  ✓ boot: feature configuration is valid");
-        return true;
+        return { ok: true, violations: [] };
     }
     catch (e) {
+        if (e instanceof BootValidationError) {
+            reportBootViolations(out, e.violations);
+            return { ok: false, violations: e.violations };
+        }
         out.err(`  ✗ boot: ${describeThrown(e)}`);
-        return false;
+        return { ok: false, violations: [unclassifiedViolation("validateBoot", e)] };
     }
 }
 function declaredTablesOf(schemaMod) {
@@ -150,7 +165,8 @@ function checkMigrationContentDrift(ctx, prevSnapshot) {
 //      added/changed but never generated → missing table → prod 500)
 //   2. boot validity: validateBoot over the composed FEATURES (QN/screen/
 //      nav/role refs). Runs only if kumiko/schema.ts exports FEATURES;
-//      honours its optional VALIDATE_BOOT_OPTIONS export.
+//      honours its optional VALIDATE_BOOT_OPTIONS export. `--json` prints
+//      this result as one JSON document on stdout.
 //   3. migration-content drift: replay every committed *.sql file and
 //      diff the result against .snapshot.json — catches a migration
 //      file whose SQL body doesn't match what its own snapshot entry
@@ -161,14 +177,32 @@ function checkMigrationContentDrift(ctx, prevSnapshot) {
 //   4. live row-level security (only with DATABASE_URL): the boot's
 //      table-state check against the real database (not the role: that is a boot-time property).
 // The DB-level gate (assertKumikoSchemaCurrent) stays at boot/deploy.
+function printBootJson(ctx, boot) {
+    const { ok, skipped, violations } = boot;
+    ctx.out.log(JSON.stringify({ boot: { ok, ...(skipped ? { skipped } : {}), violations } }));
+}
 export async function runValidateCommand(ctx) {
-    const schemaMod = await loadSchemaModOrReport(ctx);
-    if (schemaMod === undefined)
+    const jsonMode = ctx.argv.includes("--json");
+    // stdout carries exactly one JSON document in --json mode.
+    const out = jsonMode ? { log: ctx.out.err, err: ctx.out.err } : ctx.out;
+    const humanCtx = { ...ctx, out };
+    const schemaMod = await loadSchemaModOrReport(humanCtx);
+    if (schemaMod === undefined) {
+        if (jsonMode) {
+            const message = "kumiko/schema.ts could not be loaded";
+            printBootJson(ctx, {
+                ok: false,
+                violations: [{ ruleId: "unclassified/loadSchemaMod", check: "loadSchemaMod", message }],
+            });
+        }
         return 1;
+    }
     const prevSnapshot = loadPreviousSnapshot(join(ctx.migrationsDir, SNAPSHOT_FILENAME));
-    const schemaOk = checkSchemaDrift(ctx, schemaMod, prevSnapshot);
-    const bootOk = checkBootValidity(ctx.out, schemaMod);
-    const migrationsOk = checkMigrationContentDrift(ctx, prevSnapshot);
-    const rowLevelSecurityOk = await checkLiveRowLevelSecurity(ctx.out, schemaMod);
-    return schemaOk && bootOk && migrationsOk && rowLevelSecurityOk ? 0 : 1;
+    const schemaOk = checkSchemaDrift(humanCtx, schemaMod, prevSnapshot);
+    const boot = checkBootValidity(out, schemaMod);
+    const migrationsOk = checkMigrationContentDrift(humanCtx, prevSnapshot);
+    const rowLevelSecurityOk = await checkLiveRowLevelSecurity(out, schemaMod);
+    if (jsonMode)
+        printBootJson(ctx, boot);
+    return schemaOk && boot.ok && migrationsOk && rowLevelSecurityOk ? 0 : 1;
 }

package/dist/schema-cli.js

@@ -28,7 +28,7 @@ function printSchemaCliUsage(out) {
     out.log("");
     out.log("  Subcommands:");
     out.log("    generate <name>   Write a new migration from the EntityTableMeta diff");
-    out.log("    validate          Static CI gate (no DB): schema drift + validateBoot");
+    out.log("    validate [--json] Static CI gate (no DB): schema drift + validateBoot");
     out.log("    apply             Apply pending checked-in SQL files");
     out.log("    baseline          Mark checked-in migrations as applied (no SQL run)");
     out.log("    status            List applied vs pending");

package/dist/ui-types/index.d.ts

@@ -1,6 +1,7 @@
 export { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
 export type { DerivedCellRoundingTarget } from "../engine/embedded-derived.ts";
-export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedded-derived.ts";
+export { computeDerivedCellValue, roundDerivedCellValue, withDerivedCells, } from "../engine/embedded-derived.ts";
+export { findMissingConditionalRequirements, isFieldRequired, isFieldVisible, isMissingRequiredValue, } from "../engine/field-state.ts";
 export type { FormDerivationScreen } from "../engine/form-derivations.ts";
 export { applyFormDerivations, isFormDerivationInputMode, isUnusedFallbackOperand, } from "../engine/form-derivations.ts";
 export type { ParsedRefTarget } from "../engine/parse-ref-target.ts";

package/dist/ui-types/index.js

@@ -20,7 +20,8 @@
 // When adding a symbol here, verify it's either a type or a pure
 // helper with no cross-module side-effects.
 export { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
-export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedded-derived.js";
+export { computeDerivedCellValue, roundDerivedCellValue, withDerivedCells, } from "../engine/embedded-derived.js";
+export { findMissingConditionalRequirements, isFieldRequired, isFieldVisible, isMissingRequiredValue, } from "../engine/field-state.js";
 export { applyFormDerivations, isFormDerivationInputMode, isUnusedFallbackOperand, } from "../engine/form-derivations.js";
 export { parseRefTarget } from "../engine/parse-ref-target.js";
 export { ACTION_FORM_PSEUDO_ENTITY, availableSelectOptions, evalFieldCondition, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isUnchangedValue, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.399.0",
+  "version": "0.400.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,7 +203,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.399.0",
+    "@cosmicdrift/kumiko-types": "0.400.0",
     "bullmq": "^5.76.7",
     "hono": "^4.13.14",
     "i18next": "^26.1.0",
@@ -225,7 +225,7 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.399.0",
+    "@cosmicdrift/kumiko-testing": "0.400.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.3",
     "meilisearch": "^0.58.0",