@cosmicdrift/kumiko-framework 0.399.0 → 0.401.0

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/i18n/required-surface-keys.d.ts

@@ -56,3 +56,9 @@ export type RequiredLocaleGap = {
  * reported as gap owners.
  */
 export declare function findRequiredLocaleGaps(features: readonly FeatureDefinition[], requiredLocales: readonly string[]): readonly RequiredLocaleGap[];
+export declare function embeddedCellLabelKey(featureName: string, entityName: string, fieldName: string, subFieldName: string): string;
+export declare function embeddedCellOptionLabelKey(featureName: string, entityName: string, fieldName: string, subFieldName: string, value: string): string;
+/** Keys for select option labels and embedded-list cells that the screens of one feature
+ *  display. Opt-in via `requireFieldValueTranslations`: without them the renderer falls back
+ *  to the raw option value or sub-field name. */
+export declare function fieldValueTranslationKeysFromFeature(feature: FeatureDefinition): readonly string[];

package/dist/i18n/required-surface-keys.js

@@ -596,3 +596,64 @@ export function findRequiredLocaleGaps(features, requiredLocales) {
     }
     return gaps;
 }
+export function embeddedCellLabelKey(featureName, entityName, fieldName, subFieldName) {
+    return `${fieldLabelKey(featureName, entityName, fieldName)}:cell:${subFieldName}`;
+}
+export function embeddedCellOptionLabelKey(featureName, entityName, fieldName, subFieldName, value) {
+    return `${embeddedCellLabelKey(featureName, entityName, fieldName, subFieldName)}:option:${value}`;
+}
+function pushFieldValueTranslationKeys(out, featureName, entityName, fieldName, def, includeEmbeddedCells) {
+    if (def.type === "select" || def.type === "multiSelect") {
+        for (const value of def.options) {
+            out.add(selectFacetOptionKey(featureName, entityName, fieldName, value));
+        }
+        // skip: option keys are complete, nothing else to collect for select fields
+        return;
+    }
+    // skip: only multi-row embedded fields render cell labels
+    if (!includeEmbeddedCells || def.type !== "embedded" || def.multiple !== true)
+        return;
+    for (const [subName, sub] of Object.entries(def.schema)) {
+        out.add(embeddedCellLabelKey(featureName, entityName, fieldName, subName));
+        if (sub.type !== "select")
+            continue;
+        for (const value of sub.options) {
+            out.add(embeddedCellOptionLabelKey(featureName, entityName, fieldName, subName, value));
+        }
+    }
+}
+/** Keys for select option labels and embedded-list cells that the screens of one feature
+ *  display. Opt-in via `requireFieldValueTranslations`: without them the renderer falls back
+ *  to the raw option value or sub-field name. */
+export function fieldValueTranslationKeysFromFeature(feature) {
+    const out = new Set();
+    for (const screen of Object.values(feature.screens)) {
+        if (screen.type === "entityList") {
+            const entity = feature.entities?.[screen.entity];
+            if (!entity)
+                continue;
+            for (const col of screen.columns) {
+                const { field } = normalizeListColumn(col);
+                const def = entity.fields[field];
+                if (def)
+                    pushFieldValueTranslationKeys(out, feature.name, screen.entity, field, def, false);
+            }
+        }
+        else if (screen.type === "entityEdit") {
+            const entity = feature.entities?.[screen.entity];
+            if (!entity)
+                continue;
+            for (const section of screen.layout.sections) {
+                if (isExtensionEditSection(section) || section.kind === "relatedList")
+                    continue;
+                for (const spec of sectionFieldSpecs(section)) {
+                    const field = editFieldName(spec);
+                    const def = entity.fields[field];
+                    if (def)
+                        pushFieldValueTranslationKeys(out, feature.name, screen.entity, field, def, true);
+                }
+            }
+        }
+    }
+    return [...out];
+}

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-boot-input.js

@@ -41,8 +41,10 @@ export function parseValidateBootOptions(raw) {
     const navAllowlistExempt = readOptionalOption(raw, "navAllowlistExempt", isStringSet, "a Set<string>");
     const warnOnUniqueAccessRoles = readOptionalOption(raw, "warnOnUniqueAccessRoles", isBoolean, "a boolean");
     const requiredLocales = readOptionalOption(raw, "requiredLocales", isNonEmptyStringArray, "an array of non-empty strings");
+    const requireFieldValueTranslations = readOptionalOption(raw, "requireFieldValueTranslations", isBoolean, "a boolean");
     return {
         ...(requiredLocales !== undefined && { requiredLocales }),
+        ...(requireFieldValueTranslations !== undefined && { requireFieldValueTranslations }),
         ...(navAllowlist !== undefined && { navAllowlist }),
         ...(navAllowlistExempt !== undefined && { navAllowlistExempt }),
         ...(warnOnUniqueAccessRoles !== undefined && { warnOnUniqueAccessRoles }),

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.401.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.401.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.401.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.3",
     "meilisearch": "^0.58.0",

package/src/changes.json

@@ -1,4 +1,72 @@
 [
+  {
+    "version": "0.401.0",
+    "type": "improvement",
+    "title": "rebindFileRef, readGate allLinks with documents linkReadMode, documents tab entity fix",
+    "detail": "`rebindFileRef(ctx, { fileRefId, from, to })` from `@cosmicdrift/kumiko-framework/files` moves a file that is already bound (for example to an upload record or an inbound mail) onto another record's file field, for server code where a record takes over that file; pending uploads keep using `bindPendingFileRef`. It finds only files of the caller's tenant (\"not-found\" otherwise), answers \"moved\" when the file no longer sits at `from`, \"rebound\" when it was moved or already sits at `to`, and \"version-conflict\" when a parallel bind committed first, because the update is checked against the stream version. The target must be a registered file field whose accept and maxSize the file fits. A caller other than the framework system user must be able to read the file and must be able to write both the source record and field (not locked; an entity without update handler leaves the move to the system user) and the target record and field; the source row stays locked until the transaction commits, so a lock set in between is either seen or waits; a system job (`{ db, registry, user: ctx.systemUser }`) skips these checks, but the target record must exist. Rebind first, then save the id into the target field; clearing or deleting the source record afterwards leaves the file alone. An entity `readGate` takes `allLinks` as an alternative to `anyLink`: a row with links is visible only when the viewer can read every live link, and the boot validator rejects a gate that declares both. `createDocumentsFeature({ linkReadMode: \"allLinks\" })` switches the documents gate to it; the default stays `anyLink`, and the file-owner part is unchanged. `documentsTab()` now references `documents:filed-document`; before, a projection screen using it failed boot after the entity rename. Linking a document to a target entity without an update handler is now allowed for the roles in that entity's `access.write` (plus its row-level write rule); a target with neither stays unlinkable. `documents:write:link` and `documents:write:unlink` have title and field-label translations (de, en), and the documents write handlers carry an explicit `agent.risk` (link, unlink, create, update \"mid\"; import \"high\"). `createDocumentsFeature({ categoryLabels })` takes a de/en label per category (an unlabelled one shows its raw value); a key that is not in `categories` throws."
+  },
+  {
+    "version": "0.401.0",
+    "type": "breaking",
+    "title": "Boot rejects a user reference with personal: false and file accept entries that never match",
+    "detail": "`createReferenceField({ entity, personal?, reason?, required? })` builds a foreign key; a target ending in `:user` defaults to `personal: \"ref\"` and throws on `personal: false`. The boot validator now rejects a reference field to the user entity that carries `personal: false`, and a file, files, image or images field (also inside embedded schemas) whose `accept` has an entry that is not a bare lower-case extension, because the upload check compares the file's extension only. The new boot option `requireFieldValueTranslations: true` (also readable from the schema CLI input) lists every missing translation of select/multiSelect options and embedded cell labels shown by entityList/entityEdit screens in one error. `defineEntityWriteHandler` and the create/update/delete/restore wrappers return a type whose `reserveBeforeTransaction`, `beforeTransaction` and `beforeTransactionWhenNested` are `undefined`, so a handler spread into `defineWriteHandler` can add its own. user-data-rights has the export-job status option labels (de, en, es, fr, it); managed-pages branding accepts `png, jpg, jpeg, webp` instead of MIME types.",
+    "migration": "Replace `personal: false` on a reference to the user entity with `createReferenceField({ entity: \"user:user\" })` or `personal: \"ref\"`. Write `accept` entries as bare extensions (`\"pdf\"`, not `\".pdf\"` or `\"application/pdf\"`)."
+  },
+  {
+    "version": "0.400.0",
+    "type": "improvement",
+    "title": "Boot validation reports all violations at once",
+    "detail": "validateBoot runs its checks in phases and collects the violations of each phase into one BootValidationError with a `violations` list (ruleId, check, feature, message). Structural violations (duplicate API names, screen short-id collisions, unresolved query references, circular dependencies, extension usages, API exposure, reference fields, parent refs) abort before the per-feature and app-wide checks, which would only echo them. The error message starts with `Boot validation failed: N violation(s)` followed by one line per violation, each keeping its original text. A feature whose action or field wiring is invalid skips its screen check. `kumiko-schema validate` prints one ✗ line per violation and takes `--json`, which prints a single JSON document on stdout and moves the human lines to stderr."
+  },
+  {
+    "version": "0.400.0",
+    "type": "improvement",
+    "title": "Slimmer checklist cards and locale numbers in embedded lists",
+    "detail": "On narrow screens an embedded list with an `inRange` derived cell no longer shows the min and max sub-fields as their own rows. The card shows them as a hint under the measured value (\"Limit 0.05 to 0.2\", \"At least …\", \"At most …\"; new keys `kumiko.field.embedded-list.limit-range`, `limit-min`, `limit-max`). The result badge sits next to the measured value without a label. The new `embeddedList.cardHiddenCells` on an entityEdit field hides sub-fields that only steer a row (such as the kind of a checkpoint) on phone cards; boot rejects names that are not sub-fields. The desktop table is unchanged. Number and decimal cells now use the locale text input (`NumberInput`) instead of a native `type=\"number\"`, so input and read-only cells share one locale format (\"0,31\" in de, \"0.31\" in en). Tests that located these cells by role `spinbutton` must use `textbox`."
+  },
+  {
+    "version": "0.400.0",
+    "type": "improvement",
+    "title": "SQL derived fields, query-gated relatedList tabs, count badge",
+    "detail": "A derived field with `sql` (coalesce over fields, or a related-table count, countDistinct or first with optional label and conditions incl. activeOn/today/now) is computed inside the list SELECT and may set `sortable: true`, also as entityList defaultSort; JS `derive` fields stay display-only and read the SQL values. Related rows and measured fields respect the viewer's read access, a gated value is NULL. GET /api/schema removes relatedList sections (tabs, entityEdit sections, expandableRow) whose query the caller's roles cannot run, and metrics linking to a removed tab lose their navigate. `count: true` on a relatedList tab shows the tab badge from the section's own query total. A metric only becomes clickable when its entityId target resolves, and groupBy labels now also resolve for entities with a backingTable. `valueType: \"money\"` is allowed for a SQL derived `related` + `first` on a money field: amount and currency are read together and the row carries the stored money shape (no key when unset), sorting is by minor units. Ownership where-rules of a label target or related table are qualified with the subquery's own alias (a label of a row the viewer cannot read no longer leaks when the target is the outer entity), the related entity and label target must also be readable through a query handler of the viewer's roles, backingTable entities are read from their real table (also for reference labels, reference search and label sort, which returned a 500 before), an entity may derive from itself, and a sortable related derived field needs an index on the join column."
+  },
+  {
+    "version": "0.400.0",
+    "type": "improvement",
+    "title": "Entity readGate and the documents feature",
+    "detail": "`createEntity({ readGate: { anyLink, fileOwner, linkExemptRoles } })` hides a row unless the viewer can read at least one linked host (join rows with a parentRef) and the owner of the referenced file; it is applied in list, detail, eager-load and relation reads, fail-closed without the registry, and the framework system user passes. Hand-written list/detail handlers for a gated entity are rejected at boot, live signals for gated entities stay anonymous. `ParentVisibilityOption` gains `canReadEntity` and `resolveTable`. The new `documents` feature (`createDocumentsFeature({ categories, linkTargets, capture?, retention? })`) files documents with category, issue and expiry date, links them to records (link, unlink, for-record and per-type queries, expiry overview), lists them on the `documents:screen:list` projection list through `documents:query:overview` (an `expiry` state per row and an \"expiring\" filter that returns expired and soon-expiring documents), captures files saved into configured entity fields via a postSave hook, and offers an idempotent SYSTEM-only import for jobs. Updating or deleting a document needs write access to one of its linked hosts (admin roles and the system user are exempt). Reference search and sort on a readGate target now apply the gate, and `parentVisibilityFor` decides `canReadEntity` by the entity's own detail query, the same rule the file route uses, so a `liveEntities` query no longer widens what a file owner shows. A document cannot claim another user's unbound upload. A document never defaults its title to the file name."
+  },
+  {
+    "version": "0.400.0",
+    "type": "fix",
+    "title": "Hooks run for handlers that return response data; readOnly related lists",
+    "detail": "A write handler wrapped by `withResponseData` (for example `tenant:write:remove-member`) lost its lifecycle result, so postSave/postDelete hooks and projections were skipped. `WriteResult` now carries an optional `lifecycle` that the dispatcher and batch flush use and that is stripped from client responses. `EditRelatedListSection` gains `readOnly: true` for plain tables without an entity; the boot validator rejects it together with rowClick/rowActions and guard R2 skips it. The bin test helpers and `envWithoutGitOverrides` now also strip GIT_COMMON_DIR and the other git location variables."
+  },
+  {
+    "version": "0.400.0",
+    "type": "breaking",
+    "title": "An untouched money field is no longer submitted as 0",
+    "detail": "Forms seed a money field with its currency only and drop that currency-only value on submit, so a handler can tell a deliberately typed 0 from an untouched field. A currency-only value counts as missing for required checks, and the input shows empty instead of 0.00; config forms keep their plain-number contract.",
+    "migration": "A form that left a required money field untouched used to submit 0 and now fails validation; type the amount (also in e2e and DOM tests) or give the field a value through `load` or the record. Handlers that read an absent optional money field as 0 must default it themselves."
+  },
+  {
+    "version": "0.400.0",
+    "type": "improvement",
+    "title": "documents entities are filed-document and filed-document-link; safe import; split access",
+    "detail": "The documents feature registers its entities as `filed-document` (table `read_filed_documents`) and `filed-document-link` (table `read_filed_document_links`), so an app that has its own `document` entity keeps its events and tables; handler and query names follow (`documents:write:filed-document:create`, `documents:query:filed-document:list`, `documents:query:filed-document-link:list`), and so do the field label keys `documents:entity:filed-document:field:*`. `documents:write:import` now fails with a conflict (`documents.errors.import-id-taken`) and links nothing when the id is already used by a stream that is not a document; a repeat import of the same document, deleted or not, still changes nothing; the check reads the stream, so a row-level `readAccess` cannot turn a retry into a refusal. With `readAccess` set, the system user keeps reading every document, so capture and import still find the ones the rule hides. An imported document's createdAt is the time of the import, because the event store does not backdate events; issuedAt carries the business date. `createDocumentsFeature({ access })` takes either one rule for everything, as before, or `{ read, write, delete }` (type `DocumentsAccess`): read covers the lists, detail, for-record, the overviews and the list screen, write covers create, update, link and unlink; a missing read or write keeps the TenantAdmin and TenantMember default and a missing delete follows write. The readGate on the document is unchanged."
+  },
+  {
+    "version": "0.400.0",
+    "type": "improvement",
+    "title": "Embedded list as inspection checklist",
+    "detail": "Every entity field and every embedded sub-field takes `visibleWhen` and `requiredWhen` (FieldCondition). The executor enforces `requiredWhen` on create and update; it returns `validation_error` with paths like `checkpoints.0.finding`, and on update it only checks fields whose value or condition field changed. A field is required only while it is visible, and hidden values are kept. Embedded sub-fields can be `images` (with `capture`) or `files` (`maxSize`, `accept`, `maxCount`). Uploads send `subField` next to `fieldName`, and `file_refs.fieldName` stays the embedded field, so binding, tenant check, disposal, read access, GDPR forget and retention work as for top-level file fields. The new derived op `inRange` (`from: [value, min, max]`, `inside`, `outside`) writes into a select sub-field. Any derived cell can carry a row-level `when`, and server and client compute through the same `withDerivedCells`. Select sub-fields take `optionTones`; segments show the tone of the selected option, and narrow screens render cards with 44px controls and the read-only label as the card title. Boot validates the condition fields and rejects `required: true` combined with `visibleWhen`/`requiredWhen`. Saving now enforces `access.write` on embedded sub-fields per row (`ownership_denied`, path `field.subField`); before, only the read side honored sub-field access. Saving also checks each newly placed file id against the `accept`/`maxSize` of the sub-field it lands in (`file_violates_bind_target`). Boot also rejects a numeric derived op whose target is not numeric, which can break an app that derived into a text or select cell. Recipe: `samples/recipes/inspection-checklist`."
+  },
+  {
+    "version": "0.400.0",
+    "type": "fix",
+    "title": "count badge works with strict query schemas",
+    "detail": "The boot check for a relatedList with `count: true` treated every Zod object with a catchall as having open keys and skipped the `limit` and `totalCount` lookup, so a query declared with `.strict()` (catchall `never`) failed boot although it accepts both keys. Only a catchall other than `never` now counts as open; `.loose()` and `.catchall()` schemas still fail the check."
+  },
   {
     "version": "0.399.0",
     "type": "improvement",