@cosmicdrift/kumiko-framework 0.333.0 → 0.335.0

package/dist/engine/feature-ast/patch.js

@@ -33,7 +33,7 @@
 // roadmap C-Notes for the canonical-comment-attach Pattern that would
 // preserve prefixed `// kumiko-comment:` markers across roundtrips.
 import { SyntaxKind, } from "ts-morph";
-import { readNameLiteral, readNameOrRef, resolveSameFileObjectLiteral, } from "./extractors/shared.js";
+import { readNameLiteral, readNameOrRef, readPropertyKey, resolveSameFileObjectLiteral, } from "./extractors/shared.js";
 import { indent, PATTERN_INDENT, renderPattern, renderValue } from "./render.js";
 /**
  * Apply a sequence of changes to the source file in-place. The list is
@@ -202,33 +202,22 @@ const HEADER_KEY_FLAGS_BY_HANDLER_KIND = {
     queryHandler: QUERY_HANDLER_HEADER_KEY_FLAGS,
     streamHandler: STREAM_HANDLER_HEADER_KEY_FLAGS,
 };
-function propertyName(prop) {
-    const assign = prop.asKind(SyntaxKind.PropertyAssignment);
-    if (assign)
-        return readNameLiteral(assign.getNameNode()) ?? assign.getNameNode().getText();
-    const shorthand = prop.asKind(SyntaxKind.ShorthandPropertyAssignment);
-    if (shorthand)
-        return shorthand.getName();
-    return undefined;
+function lastProperty(obj) {
+    return obj.getProperties().at(-1);
 }
-// Append after the literal's last property, skipping any property this
-// same change is about to unset — avoids interleaving the two edits' spans.
-function lastRemainingProperty(obj, unsetKeys) {
-    const props = obj.getProperties();
-    for (let i = props.length - 1; i >= 0; i--) {
-        const prop = props[i];
-        if (prop === undefined)
-            continue;
-        const name = propertyName(prop);
-        if (name !== undefined && unsetKeys.has(name))
-            continue;
-        return prop;
-    }
-    return undefined;
+// ts-morph's getProperty(name) keeps the quotes of string-literal keys, so `"description": x` would never match `description`.
+function findPropertyByKey(obj, key) {
+    return obj.getProperties().find((prop) => {
+        const assign = prop.asKind(SyntaxKind.PropertyAssignment);
+        if (assign)
+            return readPropertyKey(assign) === key;
+        return prop.asKind(SyntaxKind.ShorthandPropertyAssignment)?.getName() === key;
+    });
 }
-function buildSetEdit(obj, key, value, unsetKeys) {
+// Replaces the value of an already-present key; undefined when the key is missing.
+function buildInPlaceSetEdit(obj, key, value) {
     const sourceFile = obj.getSourceFile();
-    const existing = obj.getProperty(key);
+    const existing = findPropertyByKey(obj, key);
     const assign = existing?.asKind(SyntaxKind.PropertyAssignment);
     if (assign) {
         const init = assign.getInitializer();
@@ -248,28 +237,28 @@ function buildSetEdit(obj, key, value, unsetKeys) {
             text: `${key}: ${renderValue(value, col - 1)}`,
         };
     }
-    const last = lastRemainingProperty(obj, unsetKeys);
+    return undefined;
+}
+// All missing keys go into ONE edit: separate edits would share the same
+// anchor position and depend on apply order and trailing-comma luck.
+function buildAppendEdit(obj, entries) {
+    const sourceFile = obj.getSourceFile();
+    const last = lastProperty(obj);
     const fullText = sourceFile.getFullText();
     const isSingleLineLiteral = !obj.getText().includes("\n");
     if (!last) {
-        // Empty (or fully-unset) literal — insert right after the opening brace.
+        // Empty literal — insert right after the opening brace.
         const openBrace = obj.getFirstChildByKindOrThrow(SyntaxKind.OpenBraceToken);
-        return {
-            start: openBrace.getEnd(),
-            end: openBrace.getEnd(),
-            text: ` ${key}: ${renderValue(value, 0)} `,
-        };
+        const joined = entries.map(([key, value]) => `${key}: ${renderValue(value, 0)}`).join(", ");
+        return { start: openBrace.getEnd(), end: openBrace.getEnd(), text: ` ${joined} ` };
     }
     if (isSingleLineLiteral) {
         let pos = last.getEnd();
         const hasComma = fullText[pos] === ",";
         if (hasComma)
             pos++;
-        return {
-            start: pos,
-            end: pos,
-            text: `${hasComma ? "" : ","} ${key}: ${renderValue(value, 0)}`,
-        };
+        const joined = entries.map(([key, value]) => `${key}: ${renderValue(value, 0)}`).join(", ");
+        return { start: pos, end: pos, text: `${hasComma ? "" : ","} ${joined}` };
     }
     const col = sourceFile.getLineAndColumnAtPos(last.getStart()).column;
     const indentStr = " ".repeat(col - 1);
@@ -285,13 +274,12 @@ function buildSetEdit(obj, key, value, unsetKeys) {
         // appending here would land after it. Narrower than replace; bail.
         throw new Error("updatePattern: cannot append a header field — the handler literal's last property shares a line with other code; use replace");
     }
+    const appended = entries
+        .map(([key, value]) => `\n${indentStr}${key}: ${renderValue(value, col - 1)},`)
+        .join("");
     // Reconstruct the comma here (not inserted after the value) so it lands
     // right after the value, never inside a trailing `//` comment.
-    return {
-        start: valueEnd,
-        end: lineEndPos,
-        text: `,${restOfLine}\n${indentStr}${key}: ${renderValue(value, col - 1)},`,
-    };
+    return { start: valueEnd, end: lineEndPos, text: `,${restOfLine}${appended}` };
 }
 // Whole-line delete: property was alone on its line (with its indentation
 // and trailing newline) — used when nothing else shares that line.
@@ -322,7 +310,7 @@ function buildInlineUnsetEdit(text, propStart, afterPos, hasTrailingComma) {
     return { start, end, text: "" };
 }
 function buildUnsetEdit(obj, key) {
-    const prop = obj.getProperty(key);
+    const prop = findPropertyByKey(obj, key);
     if (!prop)
         return undefined; // no-op: nothing to remove, unset is idempotent
     const sourceFile = obj.getSourceFile();
@@ -346,12 +334,7 @@ function buildUnsetEdit(obj, key) {
         return buildWholeLineUnsetEdit(sourceFile, lineStartPos, afterPos);
     return buildInlineUnsetEdit(text, propStart, afterPos, hasTrailingComma);
 }
-/**
- * Apply a `HandlerHeaderUpdate` to the header fields named in `set`/`unset`
- * only, via targeted text edits — `schemaSource`, `handlerBody`, comments,
- * and every unnamed field stay byte-identical (narrower than replacePattern).
- */
-export function updatePattern(sourceFile, change) {
+function resolveUpdatableHandlerLiteral(sourceFile, change) {
     const call = findCallForId(sourceFile, change.id);
     if (!call) {
         throw new Error(`updatePattern: no call found for ${describeId(change.id)}`);
@@ -371,6 +354,15 @@ export function updatePattern(sourceFile, change) {
     if (obj.getProperties().some((prop) => prop.isKind(SyntaxKind.SpreadAssignment))) {
         throw new Error("updatePattern: cannot update a handler literal containing a spread; use replace");
     }
+    return obj;
+}
+/**
+ * Apply a `HandlerHeaderUpdate` to the header fields named in `set`/`unset`
+ * only, via targeted text edits — `schemaSource`, `handlerBody`, comments,
+ * and every unnamed field stay byte-identical (narrower than replacePattern).
+ */
+export function updatePattern(sourceFile, change) {
+    const obj = resolveUpdatableHandlerLiteral(sourceFile, change);
     const headerFlags = HEADER_KEY_FLAGS_BY_HANDLER_KIND[change.id.kind];
     const setEntries = Object.entries(change.set).filter(([, v]) => v !== undefined);
     for (const [key] of setEntries) {
@@ -396,20 +388,47 @@ export function updatePattern(sourceFile, change) {
     // Dedupe: two identical `unset` entries would otherwise produce two
     // overlapping deletes, the second eating text past the first's shrink.
     const unsetKeys = new Set(unsetKeyList);
-    const edits = [
-        ...setEntries.map(([key, value]) => buildSetEdit(obj, key, value, unsetKeys)),
-        ...[...unsetKeys]
+    const originalText = sourceFile.getFullText();
+    try {
+        // Unsets run first and the set edits are built against the re-parsed
+        // result: an append anchor and an inline unset can otherwise share the
+        // same comma and overlap.
+        applyEditsDescending(sourceFile, [...unsetKeys]
             .map((key) => buildUnsetEdit(obj, key))
-            .filter((edit) => edit !== undefined),
-    ];
-    // Apply from the highest offset down so an earlier edit's positions,
-    // captured above against the pre-edit text, stay valid.
-    edits
-        .slice()
-        .sort((a, b) => b.start - a.start)
-        .forEach((edit) => {
+            .filter((edit) => edit !== undefined));
+        const settable = unsetKeys.size > 0 ? resolveUpdatableHandlerLiteral(sourceFile, change) : obj;
+        const inPlaceEdits = [];
+        const missingEntries = [];
+        for (const [key, value] of setEntries) {
+            const edit = buildInPlaceSetEdit(settable, key, value);
+            if (edit)
+                inPlaceEdits.push(edit);
+            else
+                missingEntries.push([key, value]);
+        }
+        applyEditsDescending(sourceFile, [
+            ...inPlaceEdits,
+            ...(missingEntries.length > 0 ? [buildAppendEdit(settable, missingEntries)] : []),
+        ]);
+    }
+    catch (error) {
+        sourceFile.replaceWithText(originalText);
+        throw error;
+    }
+}
+// Apply from the highest offset down so an earlier edit's positions,
+// captured against the pre-edit text, stay valid.
+function applyEditsDescending(sourceFile, edits) {
+    const sorted = edits.slice().sort((a, b) => b.start - a.start);
+    for (let i = 1; i < sorted.length; i++) {
+        const previous = sorted[i - 1];
+        const current = sorted[i];
+        if (previous && current && current.end > previous.start) {
+            throw new Error("updatePattern: internal error, text edits overlap");
+        }
+    }
+    for (const edit of sorted)
         sourceFile.replaceText([edit.start, edit.end], edit.text);
-    });
 }
 // =============================================================================
 // Lookup

package/dist/engine/feature-ast/patcher.d.ts

@@ -50,6 +50,7 @@ export type AddStreamHandlerArgs = {
     readonly handlerSource: string;
     readonly access?: AccessRule;
     readonly rateLimit?: RateLimitOption;
+    readonly escapeHatch?: EscapeHatchDeclaration;
 };
 export type AddHookArgs = {
     readonly type: LifecycleHookType | "validation";

package/dist/engine/feature-ast/patcher.js

@@ -162,7 +162,7 @@ export function createFeaturePatcher(sourceFile) {
                 ...(escapeHatch !== undefined && { escapeHatch }),
             });
         },
-        addStreamHandler({ name, schemaSource, handlerSource, access, rateLimit }) {
+        addStreamHandler({ name, schemaSource, handlerSource, access, rateLimit, escapeHatch }) {
             add({
                 kind: "streamHandler",
                 source: SYNTHETIC_LOC,
@@ -171,6 +171,7 @@ export function createFeaturePatcher(sourceFile) {
                 handlerBody: rawLoc(handlerSource),
                 ...(access !== undefined && { access }),
                 ...(rateLimit !== undefined && { rateLimit }),
+                ...(escapeHatch !== undefined && { escapeHatch }),
             });
         },
         addHook({ type, target, handlerSource, phase, escapeHatch }) {

package/dist/engine/feature-ast/render.js

@@ -640,7 +640,7 @@ function renderValueWithRawSlots(value, indent) {
 }
 const DEFAULT_IMPORTS = [
     'import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";',
-    'import { z } from "zod";',
+    'import * as z from "zod";',
 ];
 /**
  * Render a complete feature-file: schema-version header, imports, the

package/dist/engine/feature-entity-handlers.js

@@ -5,6 +5,24 @@ import { registerEntityCrud } from "./entity-handlers.js";
 import { resolveName } from "./handler-helpers.js";
 import { splitNamedDefinition } from "./object-form.js";
 const CRUD_VERBS = new Set(["create", "update", "delete"]);
+const CRUD_REGISTERED_VERBS = new Set([...CRUD_VERBS, "restore", "list", "detail"]);
+// A silent overwrite would drop framework behaviour that rides on the r.crud
+// handlers (e.g. writeOnly masking), so a same-name registration fails loudly.
+function assertHandlerNameFree(state, featureName, kind, handlerName) {
+    const registered = kind === "write" ? state.writeHandlers : state.queryHandlers;
+    // skip: a free name is the normal case
+    if (!Object.hasOwn(registered, handlerName))
+        return;
+    const [entityName, verb] = handlerName.split(":");
+    const crudShaped = entityName !== undefined &&
+        verb !== undefined &&
+        state.entities[entityName] !== undefined &&
+        CRUD_REGISTERED_VERBS.has(verb);
+    throw new Error(`Feature "${featureName}" registers the ${kind} handler "${handlerName}" twice.` +
+        (crudShaped
+            ? ` r.crud("${entityName}", ...) already registers that name; use a distinct name or drop the "${verb}" verb from r.crud.`
+            : " Use a distinct name."));
+}
 // Map handler name to entity via colon convention.
 // "task:create" → entity "task". Bare CRUD verbs (create/update/delete) map
 // when feature name matches an entity or the feature owns exactly one entity.
@@ -70,6 +88,7 @@ export function buildEntityHandlerMethods(state, name) {
         writeHandler(nameOrDef, schema, handler, options) {
             if (typeof nameOrDef === "object") {
                 const def = nameOrDef;
+                assertHandlerNameFree(state, name, "write", def.name);
                 state.writeHandlers[def.name] = {
                     name: def.name,
                     schema: def.schema,
@@ -101,6 +120,7 @@ export function buildEntityHandlerMethods(state, name) {
                 return { name: def.name };
             }
             const inline = requireInlineHandlerArgs("writeHandler", schema, handler, options);
+            assertHandlerNameFree(state, name, "write", nameOrDef);
             state.writeHandlers[nameOrDef] = {
                 name: nameOrDef,
                 schema: inline.schema,
@@ -116,6 +136,7 @@ export function buildEntityHandlerMethods(state, name) {
         queryHandler(nameOrDef, schema, handler, options) {
             if (typeof nameOrDef === "object") {
                 const def = nameOrDef;
+                assertHandlerNameFree(state, name, "query", def.name);
                 state.queryHandlers[def.name] = {
                     name: def.name,
                     schema: def.schema,
@@ -137,6 +158,7 @@ export function buildEntityHandlerMethods(state, name) {
                 return { name: def.name };
             }
             const inline = requireInlineHandlerArgs("queryHandler", schema, handler, options);
+            assertHandlerNameFree(state, name, "query", nameOrDef);
             state.queryHandlers[nameOrDef] = {
                 name: nameOrDef,
                 schema: inline.schema,

package/dist/engine/field-access.d.ts

@@ -1,4 +1,6 @@
 import type { EntityDefinition, SessionUser } from "./types/index.js";
+export declare function maskWriteOnlyFields<T extends Readonly<Record<string, unknown>>>(entity: EntityDefinition, row: T): T;
+export declare function dropEmptyWriteOnlyValues<T extends Readonly<Record<string, unknown>>>(entity: EntityDefinition, values: T): T;
 export declare function filterReadFields(entity: EntityDefinition, data: Readonly<Record<string, unknown>>, user: SessionUser): Record<string, unknown>;
 export declare function checkWriteFieldRoles(entity: EntityDefinition, changes: Readonly<Record<string, unknown>>, user: SessionUser): string | null;
 export declare function checkWriteFieldOwnership(entity: EntityDefinition, submittedChanges: Readonly<Record<string, unknown>>, user: SessionUser, oldRow?: Readonly<Record<string, unknown>>, rowContext?: Readonly<Record<string, unknown>>): string | null;

package/dist/engine/field-access.js

@@ -1,4 +1,40 @@
 import { normalizeAccessEntry, userCanReadFieldRow, userCanWriteFieldRow } from "./ownership.js";
+function writeOnlyFieldNames(entity) {
+    const names = [];
+    for (const [name, field] of Object.entries(entity.fields)) {
+        if (field.type === "text" && field.writeOnly === true)
+            names.push(name);
+    }
+    return names;
+}
+function maskWriteOnlyValue(value) {
+    return value === null || value === undefined || value === "" ? null : true;
+}
+// writeOnly text fields never leave the server as plaintext: set -> true,
+// empty -> null. Only keys present in the row are touched (a partial `changes`
+// stays partial). Returns the same object when the entity has no such field.
+export function maskWriteOnlyFields(entity, row) {
+    const names = writeOnlyFieldNames(entity);
+    if (names.length === 0)
+        return row;
+    const masked = { ...row };
+    for (const name of names) {
+        if (name in masked)
+            masked[name] = maskWriteOnlyValue(masked[name]);
+    }
+    return masked; // @cast-boundary engine-payload
+}
+// Write payloads: "" on a writeOnly field means "unchanged" (an untouched
+// masked input submits it), so the key is dropped before the executor sees it.
+export function dropEmptyWriteOnlyValues(entity, values) {
+    const names = writeOnlyFieldNames(entity).filter((name) => values[name] === "");
+    if (names.length === 0)
+        return values;
+    const kept = { ...values };
+    for (const name of names)
+        delete kept[name];
+    return kept; // @cast-boundary engine-payload
+}
 // Field-level read filtering. Returns a copy of `data` with fields stripped
 // if the user's roles don't grant read access OR the ownership-rule for the
 // matching role doesn't accept this concrete row. Fields without access
@@ -22,6 +58,10 @@ export function filterReadFields(entity, data, user) {
         if (!userCanReadFieldRow(user, accessMap, data)) {
             continue; // entire field stripped
         }
+        if (field.type === "text" && field.writeOnly === true) {
+            result[key] = maskWriteOnlyValue(value);
+            continue;
+        }
         // For embedded fields: filter sub-fields with access restrictions.
         // A list-embedded value is an array of rows — each row is filtered on its
         // own, so a sub-field rule can reference the row it sits in. Filtering the

package/dist/engine/index.d.ts

@@ -1,6 +1,7 @@
 export { hasAccess } from "./access.js";
 export { isPrincipalStatusPlugin, isTenantLifecycleStatusPlugin, type PrincipalProfile, type PrincipalStatus, type PrincipalStatusPlugin, TENANT_TEARDOWN_STATUSES, type TenantLifecycleStatusPlugin, } from "./active-membership.js";
 export { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./boot-validator/entity-handler.js";
+export { entityHasAnonymizableSubjectField } from "./boot-validator/pii-retention.js";
 export { collectWriteHandlerQns, MAX_TRANSFER_DEPTH, SECURITY_BASELINE_FEATURE_NAMES, type ValidateBootOptions, validateAppCustomScreenWriteQns, validateBoot, } from "./boot-validator.js";
 export { type BuildAppSchemaOptions, buildAppSchema } from "./build-app-schema.js";
 export type { ConfigFeatureSchema } from "./build-config-feature-schema.js";
@@ -40,7 +41,7 @@ export type { AddEntityArgs, AddHookArgs, AddRelationArgs, AddWriteHandlerArgs,
 export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, groupByCategory, PATTERN_LIBRARY, parseFeatureFile, parsePatternChanges, parseSourceFile, removePattern, renderFeatureFile, renderPattern, replacePattern, updatePattern, VERSION_HEADER, } from "./feature-ast/index.js";
 export { type ChangelogEntry, type ChangelogType, compareVersions, type FeatureChangelog, filterEntriesAfter, parseFeatureChangelog, sortEntries, validateChangelog, } from "./feature-changelog.js";
 export { type BuildManifestOptions, buildManifestFromRegistry, type FeatureManifest, type ManifestConfigKey, type ManifestExtension, type ManifestFeature, type ManifestSecret, serializeManifest, } from "./feature-manifest.js";
-export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, } from "./field-access.js";
+export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, maskWriteOnlyFields, } from "./field-access.js";
 export { resolveName, withResponseData } from "./handler-helpers.js";
 export { i18nKey } from "./i18n-key.js";
 export { buildSessionRoles, findForbiddenMembershipRole, isForbiddenMembershipRole, stripForbiddenMembershipRoles, } from "./membership-roles.js";
@@ -58,11 +59,11 @@ export { createRegistry } from "./registry.js";
 export type { ClampInfo, ResolveOptions } from "./resolve-config-or-param.js";
 export { resolveConfigOrParam } from "./resolve-config-or-param.js";
 export type { AssignableAppRoles, AssignableFromRole } from "./role-assignment.js";
-export { assignableAppRolesFromUsages, findForbiddenRoleAssignment, isAssignableByRole, } from "./role-assignment.js";
+export { assignableAppRolesFromUsages, assignableAppRolesOf, canActorAssignRole, findForbiddenRoleAssignment, isAssignableByRole, mergeAssignedRoles, } from "./role-assignment.js";
 export { runsInLane } from "./run-in.js";
 export type { StepListOutcome } from "./run-pipeline.js";
 export { runPipeline, runStepList } from "./run-pipeline.js";
-export { buildInsertSchema, buildUpdateSchema, fieldToZod } from "./schema-builder.js";
+export { buildInsertSchema, buildUpdateSchema, fieldToZod, SYSTEM_ONLY_JSON_SCHEMA_KEY, } from "./schema-builder.js";
 export { isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, normalizeListColumn, sectionFieldSpecs, } from "./screen-helpers.js";
 export type { TransitionGraph } from "./state-machine.js";
 export { defineTransitions, guardTransition } from "./state-machine.js";
@@ -72,7 +73,7 @@ export { describeWorkflowStepError } from "./steps/describe-workflow-step-error.
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
-export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyFactory, NotifyFn, NotifyOptions, NotifyPriority, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
+export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyFactory, NotifyFn, NotifyOptions, NotifyPriority, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases, isAgentVisibleScreen, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export type { AwaitedEventType, PipelineBuildCtx, PipelineCtx, PipelineDef, StepBuilder, StepDef, StepFailureStrategy, StepInstance, StepKind, StepNamespace, StepResolver, } from "./types/step.js";
 export { runValidation } from "./validation.js";

package/dist/engine/index.js

@@ -2,6 +2,7 @@
 export { hasAccess } from "./access.js";
 export { isPrincipalStatusPlugin, isTenantLifecycleStatusPlugin, TENANT_TEARDOWN_STATUSES, } from "./active-membership.js";
 export { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./boot-validator/entity-handler.js";
+export { entityHasAnonymizableSubjectField } from "./boot-validator/pii-retention.js";
 export { collectWriteHandlerQns, MAX_TRANSFER_DEPTH, SECURITY_BASELINE_FEATURE_NAMES, validateAppCustomScreenWriteQns, validateBoot, } from "./boot-validator.js";
 export { buildAppSchema } from "./build-app-schema.js";
 export { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, SETTINGS_HUB_WORKSPACE, } from "./build-config-feature-schema.js";
@@ -35,7 +36,7 @@ export { createBigIntField, createBooleanField, createDateField, createDecimalFi
 export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, groupByCategory, PATTERN_LIBRARY, parseFeatureFile, parsePatternChanges, parseSourceFile, removePattern, renderFeatureFile, renderPattern, replacePattern, updatePattern, VERSION_HEADER, } from "./feature-ast/index.js";
 export { compareVersions, filterEntriesAfter, parseFeatureChangelog, sortEntries, validateChangelog, } from "./feature-changelog.js";
 export { buildManifestFromRegistry, serializeManifest, } from "./feature-manifest.js";
-export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, } from "./field-access.js";
+export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, maskWriteOnlyFields, } from "./field-access.js";
 export { resolveName, withResponseData } from "./handler-helpers.js";
 export { i18nKey } from "./i18n-key.js";
 // findForbiddenMembershipRole/isForbiddenMembershipRole/
@@ -54,10 +55,10 @@ export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name.js";
 export { readClaim } from "./read-claim.js";
 export { createRegistry } from "./registry.js";
 export { resolveConfigOrParam } from "./resolve-config-or-param.js";
-export { assignableAppRolesFromUsages, findForbiddenRoleAssignment, isAssignableByRole, } from "./role-assignment.js";
+export { assignableAppRolesFromUsages, assignableAppRolesOf, canActorAssignRole, findForbiddenRoleAssignment, isAssignableByRole, mergeAssignedRoles, } from "./role-assignment.js";
 export { runsInLane } from "./run-in.js";
 export { runPipeline, runStepList } from "./run-pipeline.js";
-export { buildInsertSchema, buildUpdateSchema, fieldToZod } from "./schema-builder.js";
+export { buildInsertSchema, buildUpdateSchema, fieldToZod, SYSTEM_ONLY_JSON_SCHEMA_KEY, } from "./schema-builder.js";
 export { isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, normalizeListColumn, sectionFieldSpecs, } from "./screen-helpers.js";
 export { defineTransitions, guardTransition } from "./state-machine.js";
 export { evaluateEventMatch } from "./steps/_event-match.js";

package/dist/engine/ownership.d.ts

@@ -7,6 +7,7 @@ export declare function userCanReadFieldRow(user: SessionUser, accessMap: Owners
 export declare function userCanWriteFieldRow(user: SessionUser, accessMap: OwnershipMap | undefined, oldRow: Readonly<Record<string, unknown>>, newRow: Readonly<Record<string, unknown>>): boolean;
 export declare function normalizeAccessEntry(entry: OwnershipMap | readonly string[] | undefined): OwnershipMap | undefined;
 export declare function userCanCreateFieldRow(user: SessionUser, accessMap: OwnershipMap | undefined, newRow: Readonly<Record<string, unknown>>): boolean;
+export declare function tableNameOf(table: unknown): string;
 export declare function shiftParams(fragment: SqlFragment, shift: number): SqlFragment;
 export declare function buildOwnershipClause(user: SessionUser, accessMap: OwnershipMap | undefined, table: unknown, paramStart?: number): OwnershipClause;
 export declare function combineClauses(a: OwnershipClause, b: OwnershipClause): OwnershipClause;

package/dist/engine/ownership.js

@@ -185,7 +185,7 @@ export function userCanCreateFieldRow(user, accessMap, newRow) {
 }
 const PASS_CLAUSE = { kind: "pass" };
 const EMPTY_CLAUSE = { kind: "empty" };
-function tableNameOf(table) {
+export function tableNameOf(table) {
     if (table !== null && typeof table === "object") {
         const sym = table[KUMIKO_NAME_SYMBOL];
         if (typeof sym === "string")
@@ -298,6 +298,19 @@ export function combineClauses(a, b) {
         params: [...a.params, ...shifted.params],
     };
 }
+// The column set is constant per table object, but ruleToFragment runs on every
+// read with a where-rule.
+const columnSqlNamesByTable = new WeakMap();
+function cachedTableColumnSqlNames(table) {
+    if (table === null || typeof table !== "object")
+        return tableColumnSqlNames(table);
+    let names = columnSqlNamesByTable.get(table);
+    if (!names) {
+        names = tableColumnSqlNames(table);
+        columnSqlNamesByTable.set(table, names);
+    }
+    return names;
+}
 function ruleToFragment(rule, user, table, paramStart) {
     if (rule === "all") {
         return { kind: "sql", sqlText: "TRUE", params: [] };
@@ -311,7 +324,7 @@ function ruleToFragment(rule, user, table, paramStart) {
         // Runtime backstop for the boot-time probe (boot-validator/ownership.ts):
         // an unqualified column in a correlated subquery silently turns into a
         // fail-open tautology (fw#2639) — throw instead of shipping it.
-        assertQualifiedWhereFragment(frag.sqlText, tableColumnSqlNames(table), `ownership where-rule on "${tableNameOf(table)}"`);
+        assertQualifiedWhereFragment(frag.sqlText, cachedTableColumnSqlNames(table), `ownership where-rule on "${tableNameOf(table)}"`);
         return { kind: "sql", sqlText: frag.sqlText, params: frag.params };
     }
     // FromRule

package/dist/engine/pattern-library/mixed-schemas.js

@@ -1,5 +1,5 @@
 // Mixed pattern schemas (header form + opaque body source).
-import { accessRuleField, HOOK_TYPE_OPTIONS, HTTP_METHOD_OPTIONS } from "./shared-fields.js";
+import { accessRuleField, agentDescriptionField, agentHintsField, HOOK_TYPE_OPTIONS, HTTP_METHOD_OPTIONS, } from "./shared-fields.js";
 // --- Mixed patterns (header form + opaque body source) --------------------
 export const screenSchema = {
     kind: "screen",
@@ -71,20 +71,8 @@ export const writeHandlerSchema = {
             readOnly: true,
         },
         accessRuleField,
-        {
-            path: "description",
-            label: { en: "Description", de: "Beschreibung" },
-            hint: {
-                en: "Prose the AI agent sees as the tool description. Without it the handler stays invisible to the agent.",
-            },
-            input: "textarea",
-        },
-        {
-            path: "agent",
-            label: { en: "Agent hints", de: "Agent-Hinweise" },
-            hint: { en: "expose override + risk level for the AI-agent manifest." },
-            input: "json-readonly",
-        },
+        agentDescriptionField,
+        agentHintsField,
         {
             path: "rateLimit",
             label: { en: "Rate limit", de: "Rate-Limit" },
@@ -126,20 +114,8 @@ export const queryHandlerSchema = {
             readOnly: true,
         },
         accessRuleField,
-        {
-            path: "description",
-            label: { en: "Description", de: "Beschreibung" },
-            hint: {
-                en: "Prose the AI agent sees as the tool description. Without it the handler stays invisible to the agent.",
-            },
-            input: "textarea",
-        },
-        {
-            path: "agent",
-            label: { en: "Agent hints", de: "Agent-Hinweise" },
-            hint: { en: "expose override + risk level for the AI-agent manifest." },
-            input: "json-readonly",
-        },
+        agentDescriptionField,
+        agentHintsField,
         {
             path: "rateLimit",
             label: { en: "Rate limit", de: "Rate-Limit" },
@@ -549,6 +525,16 @@ export const defineEventSchema = {
             language: "zod",
             readOnly: true,
         },
+        {
+            path: "piiFields",
+            label: { en: "PII fields (source)", de: "PII-Felder (Source)" },
+            hint: {
+                en: 'Which payload fields are encrypted, or "none" when the event carries no PII.',
+            },
+            input: "code-block",
+            language: "typescript",
+            readOnly: true,
+        },
         {
             path: "version",
             label: { en: "Version", de: "Version" },

package/dist/engine/pattern-library/shared-fields.d.ts

@@ -117,4 +117,6 @@ export declare const ID_TYPE_OPTIONS: readonly [{
         readonly de: "Serial Integer";
     };
 }];
+export declare const agentDescriptionField: FormFieldSpec;
+export declare const agentHintsField: FormFieldSpec;
 export declare const accessRuleField: FormFieldSpec;

package/dist/engine/pattern-library/shared-fields.js

@@ -30,6 +30,23 @@ export const ID_TYPE_OPTIONS = [
     { value: "uuid", label: { en: "UUID (default)", de: "UUID (Standard)" } },
     { value: "serial", label: { en: "Serial integer", de: "Serial Integer" } },
 ];
+export const agentDescriptionField = {
+    path: "description",
+    label: { en: "Description", de: "Beschreibung" },
+    hint: {
+        en: "Prose the AI agent sees as the tool description. Without it the handler stays invisible to the agent.",
+    },
+    input: "textarea",
+};
+export const agentHintsField = {
+    path: "agent",
+    label: { en: "Agent hints", de: "Agent-Hinweise" },
+    hint: {
+        en: "expose override + risk level for the AI-agent manifest.",
+        de: "Expose-Override und Risikostufe für das KI-Agent-Manifest.",
+    },
+    input: "json-readonly",
+};
 export const accessRuleField = {
     path: "access",
     label: { en: "Access", de: "Zugriff" },

package/dist/engine/registry-facade.js

@@ -113,6 +113,9 @@ export function buildRegistryFacade(state) {
         getHandlerFeature(qualifiedHandler) {
             return state.handlerFeatureMap.get(qualifiedHandler);
         },
+        getJobFeature(qualifiedJobName) {
+            return state.jobFeatureMap.get(qualifiedJobName);
+        },
         getAllMetrics() {
             return state.metricMap;
         },

package/dist/engine/role-assignment.d.ts

@@ -1,4 +1,6 @@
-export type AssignableFromRole = "User" | "Member" | "Editor" | "Admin" | "TenantAdmin" | "SystemAdmin";
+import type { Registry } from "./types/feature.js";
+declare const ASSIGNABLE_FROM_ROLE_LIST: readonly ["User", "Member", "Editor", "Admin", "TenantAdmin", "SystemAdmin"];
+export type AssignableFromRole = (typeof ASSIGNABLE_FROM_ROLE_LIST)[number];
 /** App role → lowest built-in role allowed to assign it. */
 export type AssignableAppRoles = ReadonlyMap<string, AssignableFromRole>;
 export declare const DEFAULT_APP_ROLE_ASSIGNABLE_FROM: AssignableFromRole;
@@ -8,4 +10,8 @@ export declare function assignableAppRolesFromUsages(usages: readonly {
 }[]): AssignableAppRoles;
 /** True when `actorRole` ranks at least as high as the role an app role is assignable from. */
 export declare function isAssignableByRole(assignableFrom: AssignableFromRole, actorRole: AssignableFromRole): boolean;
+export declare function canActorAssignRole(actorRoles: readonly string[], role: string, assignableAppRoles?: AssignableAppRoles): boolean;
+export declare function mergeAssignedRoles(actorRoles: readonly string[], assignedRoles: readonly string[], targetCurrentRoles: readonly string[], assignableAppRoles: AssignableAppRoles): readonly string[];
+export declare function assignableAppRolesOf(registry: Pick<Registry, "getExtensionUsages">): AssignableAppRoles;
 export declare function findForbiddenRoleAssignment(actorRoles: readonly string[], assignedRoles: readonly string[], targetCurrentRoles: readonly string[], assignableAppRoles?: AssignableAppRoles): string | undefined;
+export {};