@cosmicdrift/kumiko-framework 0.399.0 → 0.400.0

package/agents/api/framework-engine.md

@@ -30,10 +30,10 @@ function createBigIntField<R extends true | false = false>(overrides?: Partial<O
 function createBooleanField<R extends true | false = false>(overrides?: Partial<Omit<BooleanFieldDef, "type" | "required">> & { required?: R; }): BooleanFieldDef & { required: R; default: boolean; };
 function createDateField<R extends true | false = false>(overrides?: Partial<Omit<DateFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): DateFieldDef & { required: R; };
 function createDecimalField<R extends true | false = false>(config: { precision: number; scale: number; } & Partial<Omit<DecimalFieldDef, "type" | "precision" | "scale" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): DecimalFieldDef & { required: R; };
-function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef; // Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`).
+function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef; // Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`), never persisted.
 function createEmbeddedField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef;
 function createEmbeddedListField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | "multiple" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef & { multiple: true; };
-function createEntity<const F, const T extends EntityTenancy = "tenant">(def: { table?: string; fields: F; description?: string; softDelete?: boolean; systemStream?: boolean; eventVersion?: number; eventMigrations?: EntityDefinition["eventMigrations"]; searchWeight?: number; defaultCurrency?: string; transitions?: Readonly<Record<string, Readonly<Record<string, string[]>>>>; lockedWhen?: EntityDefinition["lockedWhen"]; indexes?: EntityIndexDef[]; idType?: "serial" | "uuid"; access?: EntityDefinition["access"]; parentRef?: EntityDefinition["parentRef"]; retention?: RetentionDef; derivedFields?: EntityDefinition["derivedFields"]; tenancy?: T; transferable?: boolean; attachedFileAccess?: EntityDefinition["attachedFileAccess"]; }): F extends FieldsMap ? EntityDefinition<F, T> : never;
+function createEntity<const F, const T extends EntityTenancy = "tenant">(def: { table?: string; fields: F; description?: string; softDelete?: boolean; systemStream?: boolean; eventVersion?: number; eventMigrations?: EntityDefinition["eventMigrations"]; searchWeight?: number; defaultCurrency?: string; transitions?: Readonly<Record<string, Readonly<Record<string, string[]>>>>; lockedWhen?: EntityDefinition["lockedWhen"]; indexes?: EntityIndexDef[]; idType?: "serial" | "uuid"; access?: EntityDefinition["access"]; parentRef?: EntityDefinition["parentRef"]; readGate?: EntityDefinition["readGate"]; retention?: RetentionDef; derivedFields?: EntityDefinition["derivedFields"]; tenancy?: T; transferable?: boolean; attachedFileAccess?: EntityDefinition["attachedFileAccess"]; }): F extends FieldsMap ? EntityDefinition<F, T> : never;
 function createEntityExecutor<E extends EntityDefinition>(entityName: string, entity: E): { table: EntityTable; executor: EventStoreExecutor<EntityRow<E>>; };
 function createFileField(overrides?: Partial<Omit<FileFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FileFieldDef;
 function createFilesField(overrides?: Partial<Omit<FilesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FilesFieldDef;
@@ -120,6 +120,7 @@ function normalizeEditField(f: EditFieldSpec): Exclude<EditFieldSpec, string>;
 function normalizeListColumn(c: ListColumnSpec): Exclude<ListColumnSpec, string>;
 function pageRows<TRow extends Readonly<Record<TSortField, PagedListRowValue>> & { id: string; }, TSortField extends string>(rows: TRow[], request: PagedListRequest<TSortField>, options: { searchFields: TSortField[]; defaultSort: TSortField; }): CursorResult<TRow>;
 function pagedListSchema<const TSortField extends string>(sortableFields: [ TSortField, ...TSortField[] ]): …;
+function parentVisibilityFor(ctx: HandlerContext, user: SessionUser): ParentVisibilityOption;
 function parseChangesetChanges(markdown: string, source: string): PendingChange[]; // Parse structured upgrade metadata embedded in a Changeset body.
 function parseFeatureChangelog(raw: string, featureName: string): FeatureChangelog | null; // Parse a changes.json body.
 function parseQn(value: string): ParsedQn;
@@ -145,6 +146,7 @@ function tenantChannel(tenantId: TenantId): string;
 function toKebab(input: string): string;
 function typedPayload<TPayload>(event: { type: string; payload: Record<string, unknown>; }, eventDef: EventDef<TPayload>): TPayload;
 function unwrapWorkflowStepError(error: unknown): unknown;
+function userCanWriteFieldRow(user: SessionUser, accessMap: OwnershipMap | undefined, oldRow: Readonly<Record<string, unknown>>, newRow: Readonly<Record<string, unknown>>): boolean;
 function validateAppCustomScreenWriteQns(appRoot: string, knownQns: ReadonlySet<string>): void; // Boot-time scan of app `src/**` for `dispatcher.write("…")` string literals.
 function validateBoot(rawFeatures: FeatureDefinition[], options?: ValidateBootOptions): void; // Validates all feature configurations at boot time.
 function validateBundledListsOptions(options: unknown): void;
@@ -482,6 +484,7 @@ type EditRelatedListSection = {
   id?: string; // Kebab-case tab id, used as the `?tab=` value.
   kind: "relatedList";
   title: string;
+  readOnly?: boolean; // Rows are aggregates or other values with no record of their own, so they lead nowhere on purpose.
   query: string; // Fully qualified query QN.
   parentParam?: string; // Query-payload key the parent record's id is passed under.
   parentFilter?: {
@@ -506,6 +509,7 @@ type EditRelatedListSection = {
   rowTone?: RelatedListRowTone; // Tints rows whose field matches — a declarative rule, not a function, so the screen definition stays serializable.
   toolbarActions?: RelatedListToolbarAction[]; // Toolbar actions above the table — same type and dispatch semantics as `entityList`/`projectionList`'s `toolbarActions` ("+ Anlegen" etc.), plus `visible`/`params` evaluated against the parent record (see RelatedListToolbarAction).
   countField?: string; // Record field rendered as a count badge in the tab label when the enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
+  count?: true; // Tab badge counted from this section's own query (`limit: 1, totalCount: true` → `total`), so it matches the tab's rows and stays live.
   actions?: RowAction[]; // Rendered top-right in the section's Card title row — same navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`, evaluated against the parent record.
   emptyState?: RelatedListEmptyStateSpec; // Rendered inside the section's Card in place of the table when this section's query returns zero rows.
 };
@@ -532,6 +536,7 @@ type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTenancy =
     write?: OwnershipMap;
   }; // Row-level ownership rules (H.2).
   parentRef?: ParentRefDef; // Join-row carrier reference.
+  readGate?: ReadGateDef; // Declarative read gate for rows readable only through other rows (a link to a visible host, a file whose owner is readable).
   retention?: RetentionDef; // Default retention policy for this entity.
   derivedFields?: DerivedFieldsMap; // Read-time computed fields, keyed by name.
   description?: string; // Optional free-text semantics for the AI agent manifest — see TextFieldDef.description.
@@ -942,7 +947,7 @@ type JobTrigger =
     manual: true;
   }
 ;
-type JsonbFieldDef = ResolvedPiiFlags & {
+type JsonbFieldDef = PiiAndFieldState & {
   type: "jsonb";
   description?: string;
   emptyValue?: JsonbEmptyValue; // `"array"`: the field holds a JSON array, so a row that never wrote it reads `[]` and writes take an array.
@@ -1798,6 +1803,7 @@ type WriteResult<TData = unknown> =
   | {
     isSuccess: true;
     data: TData;
+    lifecycle?: LifecycleResult; // The executor result behind a handler that answers with its own `data`.
   }
   | WriteFailure
 ;

package/agents/api/framework-ui-types.md

@@ -10,13 +10,17 @@ Import from `@cosmicdrift/kumiko-framework/ui-types`. Types used here but not ex
 function applyFormDerivations(values: unknown, screen: FormDerivationScreen): unknown; // Recomputes every derived head field of an action form from its inputs.
 function availableSelectOptions(field: SelectOptionRules, values: Record<string, unknown>): string[]; // Options of a select field that are offered for the given row values, in declaration order.
 function cardColumnRoles<C extends CardRoleColumn>(columns: C[]): CardColumnRoles<C>;
-function computeDerivedCellValue(op: EmbeddedDerivedCellDef["op"], values: (number | undefined)[]): number | undefined; // Computes a derived cell from its source values.
+function computeDerivedCellValue(op: NumericDerivedOp, values: (number | undefined)[]): number | undefined; // Computes a derived cell from its source values.
 function evalFieldCondition(cond: FieldCondition, values: Record<string, unknown>): boolean; // Evaluates a declarative FieldCondition against the current row/form values.
+function findMissingConditionalRequirements(fields: Readonly<Record<string, FieldDefinition>>, values: Record<string, unknown>, previous?: Record<string, unknown>): string[]; // Paths of fields (and embedded sub-fields) whose `requiredWhen` holds while the value is missing.
 function findUnavailableSelectOptions(fields: Readonly<Record<string, FieldDefinition>>, values: Record<string, unknown>, previous?: Record<string, unknown>): UnavailableSelectOption[]; // Select values that violate a `conditionalOptions` rule.
 function formalLocaleTag<Locale extends string>(locale: Locale): `${Locale}-x-formal`;
 function isExtensionEditSection(section: EditSectionSpec): section is EditExtensionSection;
+function isFieldRequired(def: RequiredState, values: Record<string, unknown>): boolean;
+function isFieldVisible(def: FieldStateConditions, values: Record<string, unknown>): boolean;
 function isFormDerivationInputMode(screen: FormDerivationScreen, values: unknown, field: string): boolean; // True when `field` is a `listSum` without `whenEmpty` whose list has no rows: the sum has nothing to add up, so the user types the value.
 function isFormatSpec(r: unknown): r is FormatSpec;
+function isMissingRequiredValue(value: unknown): boolean;
 function isRecordLocked(lockedWhen: FieldCondition | undefined, row: Readonly<Record<string, unknown>>): boolean;
 function isUiAccessGranted(access: AccessRule | undefined, userRoles: string[] | undefined): boolean;
 function isUnchangedValue(a: unknown, b: unknown): boolean;
@@ -26,6 +30,7 @@ function resolveNavParentScreen(screens: ScreenDefinition[], detail: ScreenDefin
 function resolveTranslationValue(value: TranslationValue, locale: string, params?: Readonly<Record<string, unknown>>): string; // Resolve a TranslationValue to display text: a plural entry picks its CLDR category via `Intl.PluralRules` from `params.count`, falling back to `other` when `count` is missing, non-finite, or `locale` is invalid.
 function roundDerivedCellValue(value: number, target: DerivedCellRoundingTarget): number; // Rounds a derived cell's computed value to the precision its target sub-field declares — commercial rounding (round-half-away-from-zero, correct for signed minor-unit money).
 function translationValueOtherText(value: TranslationValue): string; // Text-only reading of a TranslationValue — the CLDR `other` form for a plural entry, or the string as-is.
+function withDerivedCells(row: unknown, derived: Readonly<Record<string, EmbeddedDerivedCellDef>>, targets: Readonly<Record<string, DerivedCellRoundingTarget>>): unknown; // Recomputes every derived cell of an embedded-list row from its raw values, overwriting whatever the client sent instead of merely checking it — the server is the authority for derived cells.
 ```
 
 ## Constants
@@ -331,12 +336,12 @@ type EditWriteFormSection = {
   submitLabel?: string; // i18n-key for the submit button.
   actions?: RowAction[]; // Rendered top-right in the section's Card title row — same navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`, evaluated against the same record.
 };
-type EmbeddedDerivedCellDef = { // A cell computed from other cells of the same row.
-  op: "multiply" | "sum" | "subtract" | "percent"; // `percent` = `from[0] * from[1] / 100` (exactly two sources, e.g. amount and rate).
-  from: string[];
+type EmbeddedDerivedCellDef = ({ op: "multiply" | "sum" | "subtract" | "percent"; from: string[]; } | { op: "inRange"; from: string[]; inside: string; outside: string; }) & { // A cell computed from other cells of the same row.
+  when?: Exclude<FieldCondition, boolean>; // Row-level condition on a sibling sub-field.
 };
 type EmbeddedListEditSpec = {
   readOnlyCells?: string[]; // Sub-fields shown as read-only cells; every other cell stays editable.
+  cardHiddenCells?: string[]; // Sub-fields that only steer a row (e.g. the kind that decides which controls appear) and are not shown on phone cards; the desktop table still shows them.
   fixedRows?: boolean; // `true` keeps the rows as they are: no add, remove, duplicate, move or paste-appended rows.
 };
 type EntityEditAction = RowAction & {
@@ -507,7 +512,7 @@ type SecretsEditScreenDefinition = {
   access?: AccessRule;
 };
 type SelectOptionTone = (typeof SELECT_OPTION_TONES)[number];
-type TextFieldDef = ResolvedPiiFlags & {
+type TextFieldDef = PiiAndFieldState & {
   type: "text";
   description?: string; // Optional free-text semantics for the AI agent manifest — never rendered; the i18n label is what users see.
   maxLength?: number;

package/agents/api/renderer-web.md

@@ -499,7 +499,7 @@ interface FileFieldProps extends FieldBase {
   entityType?: string; // Binds the upload to a specific entity field; the `/api/files` endpoint then validates `accept`/`maxSize` server-side against that field's definition.
   fieldName?: string;
 }
-type FileRefTarget = Pick<FileUploadFormDataInput, "entityType" | "entityId" | "fieldName" | "actionForm">;
+type FileRefTarget = Pick<FileUploadFormDataInput, "entityType" | "entityId" | "fieldName" | "subField" | "actionForm">;
 type FloatingPanelGeometry = {
   x: number;
   y: number;
@@ -776,6 +776,7 @@ type InputProps =
     hasError?: boolean;
     radioVariant?: "list" | "card"; // `"card"` renders the radio group as bordered cards with label plus optional description per option and always uses the radio group, regardless of option count or `display`.
     display?: "radio" | "dropdown"; // Requested presentation.
+    optionTones?: Readonly<Partial<Record<string, SelectOptionTone>>>; // Tone per option value; the selected segment of a radio presentation takes its colors.
   }
   | ({ kind: "combobox"; id: string; name: string; options: { value: string; label: string; }[]; disabled?: boolean; required?: boolean; hasError?: boolean; placeholder?: string; searchPlaceholder?: string; emptyText?: string; onSearchChange?: (q: string) => void; loading?: boolean; onCreate?: () => void; createLabel?: string; } & ({ multiple?: false; value: string; onChange: (v: string) => void; } | { multiple: true; value: string[]; onChange: (v: string[]) => void; }))
   | {