@cosmicdrift/kumiko-framework 0.336.1 → 0.338.0

package/dist/db/queries/seed-context.js

@@ -1,25 +1,25 @@
 import { unsafeReadRetrying } from "../query.js";
 export async function selectUserByEmail(db, email) {
-    const rows = (await unsafeReadRetrying(db, `SELECT id::text AS id, email, tenant_id::text AS tenant_id
+    const rows = await unsafeReadRetrying(db, `SELECT id::text AS id, email, tenant_id::text AS tenant_id
      FROM read_users
      WHERE email = $1
-     LIMIT 1`, [email]));
+     LIMIT 1`, [email]);
     const row = rows[0];
     if (!row)
         return null;
     return { id: row.id, email: row.email, tenantId: row.tenant_id };
 }
 export async function selectMembershipsOfUser(db, userId) {
-    return (await unsafeReadRetrying(db, `SELECT m.user_id::text AS user_id,
+    return unsafeReadRetrying(db, `SELECT m.user_id::text AS user_id,
             m.tenant_id::text AS tenant_id,
             e.tenant_id::text AS stream_tenant_id,
             m.roles
      FROM read_tenant_memberships m
      JOIN kumiko_events e ON e.aggregate_id = m.id AND e.version = 1
-     WHERE m.user_id = $1`, [userId]));
+     WHERE m.user_id = $1`, [userId]);
 }
 export async function selectAllTenants(db) {
-    return (await unsafeReadRetrying(db, `SELECT id::text AS id, name, key AS tenant_key
+    return unsafeReadRetrying(db, `SELECT id::text AS id, name, key AS tenant_key
      FROM read_tenants
-     ORDER BY inserted_at`, []));
+     ORDER BY inserted_at`, []);
 }

package/dist/db/tenant-db.js

@@ -61,7 +61,7 @@ export function unsafeRawForDeclaredStep(holder, reason) {
                 "createUncheckedSystemDb, or createSystemDbView — no declared unsafeRaw runner bound.",
         });
     }
-    return runner(reason);
+    return runner(reason, true);
 }
 const systemDbRebinders = new WeakMap();
 // Rebinds a hook's own escapeHatch onto ctx.systemDb, mirroring withUnsafeRawGrant: always
@@ -96,9 +96,15 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
         }
         return dbOutsideTransaction;
     }
-    function grantedUnsafeRawRunner(reason) {
+    function grantedUnsafeRawRunner(reason, forwardedDeclaredStep) {
         if (gate?.kind === "source-tenant-db") {
-            return unsafeRawForDeclaredStep(db, reason);
+            const sourceRunner = declaredUnsafeRawRunners.get(db);
+            if (!sourceRunner) {
+                throw new InternalError({
+                    message: "createSystemDbView received a TenantDb with no declared unsafeRaw runner bound.",
+                });
+            }
+            return sourceRunner(reason, forwardedDeclaredStep);
         }
         if (reason.trim().length === 0) {
             throw new Error("unsafeRaw requires a non-empty reason");
@@ -109,7 +115,8 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
                     `${gate.deniedCallerLabel} to allow unsafeRaw.`,
             });
         }
-        report("unsafe-raw", reason);
+        // Engine-forwarded steps carry their own declared reason; a caller-supplied one never reaches the audit trail.
+        report("unsafe-raw", forwardedDeclaredStep ? reason : (gate?.grant?.reason ?? reason));
         const runner = tenantDbRunner(db);
         const personalDataGate = personalDataGates.get(db);
         return personalDataGate ? gatedRunner(runner, personalDataGate) : runner;
@@ -143,7 +150,7 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
             report("acknowledge-cross-tenant", reason);
             return db;
         },
-        unsafeRaw: grantedUnsafeRawRunner,
+        unsafeRaw: (reason) => grantedUnsafeRawRunner(reason, false),
         outsideTransaction: {
             assertTenantMatch(tenantId) {
                 if (tenantId !== db.tenantId) {
@@ -419,7 +426,7 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             // @cast-boundary type-brand — GlobalWrites is only present in the type when TTable is not ExecutorOnly; the object above always carries the methods.
         };
     }
-    function grantedUnsafeRawRunner(reason) {
+    function grantedUnsafeRawRunner(reason, forwardedDeclaredStep) {
         if (reason.trim().length === 0) {
             throw new Error("unsafeRaw requires a non-empty reason");
         }
@@ -433,14 +440,15 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
                     "the handler or hook to allow unsafeRaw.",
             });
         }
-        report("unsafe-raw", reason);
+        // Engine-forwarded steps carry their own declared reason; a caller-supplied one never reaches the audit trail.
+        report("unsafe-raw", forwardedDeclaredStep ? reason : (grants?.unsafeRaw?.reason ?? reason));
         return personalDataGate ? gatedRunner(db, personalDataGate) : db;
     }
     const tenantDb = {
         tenantId,
         mode,
         global: globalTable,
-        unsafeRaw: grantedUnsafeRawRunner,
+        unsafeRaw: (reason) => grantedUnsafeRawRunner(reason, false),
         selectMany(table, where, options) {
             const filter = readWhere(table, where);
             return withDbSpan("select", table, async () => bunSelectMany(db, table, filter, options));

package/dist/derivatives/derivatives-context.js

@@ -97,8 +97,11 @@ function resolveOverlayLayer(layer, qrContext, tenantId) {
 // the spec, so a resolver whose target changes (e.g. a base-URL rotation)
 // invalidates the cache instead of serving a stale target under the old key.
 async function resolveOverlaySpec(spec, row, registry, tenantId) {
-    if (!spec.overlays || spec.overlays.length === 0)
-        return spec;
+    // `resolvedOverlays` is framework-internal; a caller-supplied value must
+    // never reach the renderer past the token resolution below.
+    if (!spec.overlays || spec.overlays.length === 0) {
+        return spec.resolvedOverlays === undefined ? spec : { ...spec, resolvedOverlays: undefined };
+    }
     const qrContext = spec.overlays.some((layer) => layer.kind === "qr")
         ? resolveQrOverlayContext(row, registry)
         : undefined;

package/dist/engine/boot-validator/access-declarations.js

@@ -1,3 +1,4 @@
+import { escapeHatchGrantsProblem } from "@cosmicdrift/kumiko-types/handlers";
 import { accessAllowsAnonymous, declaredPersonalData, personalFieldNames, } from "../personal-data-fields.js";
 import { ANONYMOUS_ROLE } from "../system-user.js";
 import { collectZodObjectKeys } from "./zod-shape.js";
@@ -48,13 +49,18 @@ function validateOpenToAllReason(feature, kind, handlerName, access) {
         "authenticated user may call this handler. `{ openToAll: true }` is no longer accepted.");
 }
 function validateEscapeHatchReason(feature, kind, handlerName, escapeHatch) {
-    // skip: no escapeHatch declared, or its reason is already non-empty
-    if (!escapeHatch || escapeHatch.reason.trim().length > 0)
-        return;
-    throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
-        `{ escapeHatch: { reason: "" } } — the reason must be a non-empty string ` +
-        "explaining why this handler needs db.global() write access, a SYSTEM identity switch " +
-        "or a cross-tenant ctx.queryProjection({ unsafeAllTenants: true }) read.");
+    if (escapeHatch) {
+        const grantsProblem = escapeHatchGrantsProblem(escapeHatch);
+        if (grantsProblem !== undefined) {
+            throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid escapeHatch — ${grantsProblem}`);
+        }
+        if (escapeHatch.reason.trim().length === 0) {
+            throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
+                `{ escapeHatch: { reason: "" } } — the reason must be a non-empty string ` +
+                "explaining why this handler needs db.global() write access, a SYSTEM identity switch " +
+                "or a cross-tenant ctx.queryProjection({ unsafeAllTenants: true }) read.");
+        }
+    }
 }
 function validatePersonalDataOnlyOnWrite(feature, kind, handlerName, access) {
     // skip: write handlers may declare personalData, or it wasn't declared here

package/dist/engine/boot-validator/entity-handler.d.ts

@@ -22,3 +22,4 @@ export declare function validateImageVariants(feature: FeatureDefinition): void;
 export declare function validateTransitions(feature: FeatureDefinition): void;
 export declare function validateExtendSchemaCollisions(feature: FeatureDefinition): void;
 export declare function validateDerivedFieldCollisions(feature: FeatureDefinition): void;
+export declare function validateSearchableFieldReadAccess(feature: FeatureDefinition): void;

package/dist/engine/boot-validator/entity-handler.js

@@ -784,3 +784,29 @@ export function validateDerivedFieldCollisions(feature) {
         }
     }
 }
+// --- Searchable fields with restricted read access ---
+// The search index is tenant-wide, not per-role: `search` matches every
+// searchable field and `filterReadFields` only strips the response afterwards.
+// A role that cannot read the field could still guess its value from match
+// counts, so the combination is rejected until the index can filter per role.
+export function validateSearchableFieldReadAccess(feature) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+        for (const [fieldName, field] of Object.entries(entity.fields)) {
+            if (field.type !== "text")
+                continue;
+            if (!field.searchable)
+                continue;
+            const readAccess = field.access?.read;
+            if (readAccess === undefined)
+                continue;
+            const isUnrestricted = Array.isArray(readAccess)
+                ? readAccess.length === 0
+                : Object.keys(readAccess).length === 0;
+            if (isUnrestricted)
+                continue;
+            throw new Error(`Field "${fieldName}" on entity "${entityName}" cannot be searchable with a restricted ` +
+                "access.read — the search index is not filtered per role, so search matches would leak " +
+                'the value to roles that cannot read it. Drop `searchable`/`find: "fuzzy"` or `access.read`.');
+        }
+    }
+}

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

@@ -9,7 +9,7 @@ import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext.
 import { validateFeatureBootChecks } from "./boot-check.js";
 import { validateCircularDeps, validateConfigKeyAllowPerRequest, validateConfigKeyBacking, validateConfigKeyBounds, validateConfigKeyComputed, validateConfigKeyOptionsQuery, validateConfigKeyPiiEncrypted, validateConfigKeyRequired, validateConfigReads, warnOnToggleableDependencies, } from "./config-deps.js";
 import { collectDetailForScreens } from "./detail-screens.js";
-import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateEntitySelectOptionsQuery, validateExtendSchemaCollisions, validateExtensionPreSaveWiring, validateFileFields, validateHandlerAccess, validateImageVariants, validateLocatedTimestamps, validateMultiSelectFields, validateMultiStreamProjections, validateReferenceFields, validateTransitions, } from "./entity-handler.js";
+import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateEntitySelectOptionsQuery, validateExtendSchemaCollisions, validateExtensionPreSaveWiring, validateFileFields, validateHandlerAccess, validateImageVariants, validateLocatedTimestamps, validateMultiSelectFields, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
 import { validateEntityListScreens } from "./entity-list-screens.js";
 import { validateGdprStoragePersistence } from "./gdpr-storage.js";
 import { validateGlobalTenancyEntities } from "./global-tenancy.js";
@@ -118,6 +118,7 @@ export function validateBoot(rawFeatures, options) {
         validateCircularDeps(feature.name, featureMap);
         if (validateEncryptedFields(feature))
             hasEncryptedFields = true;
+        validateSearchableFieldReadAccess(feature);
         if (validateFileFields(feature))
             hasFileFields = true;
         validatePiiAndRetention(feature);

package/dist/engine/boot-validator/pii-retention.js

@@ -12,6 +12,12 @@ const FRAMEWORK_TIMESTAMP_FIELDS = new Set([
 // macht nur den Sanity-Check damit Tippfehler ("30days") frueh sichtbar
 // werden statt erst beim ersten Cleanup-Run.
 const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
+const FILE_FIELD_TYPES = new Set([
+    "file",
+    "image",
+    "files",
+    "images",
+]);
 // Excludes subjectRef: its `personal: "ref"` union member structurally
 // forbids `anonymize` (packages/types/src/fields.ts) — #2336.
 function hasAnonymizableSubjectField(annot) {
@@ -184,7 +190,11 @@ export function validatePiiAndRetention(feature) {
             const noAnnotation = annotCount === 0 && !annot.allowPlaintext;
             if (noAnnotation) {
                 const lower = fieldName.toLowerCase();
-                if (PII_DIRECT_NAME_HINTS.has(lower)) {
+                if (FILE_FIELD_TYPES.has(field.type)) {
+                    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+                    console.warn(`[kumiko:boot] [Feature ${feature.name}] File field "${fieldName}" on entity "${entityName}" has no personal annotation. A forget with strategy "delete" then only severs the uploader link and keeps the binary. If the file holds personal data, mark it { personal: "self" } or { personal: { of: "<ownerField>" } }. If it is business data, set { personal: false, reason: "is_business_data" } to silence.`);
+                }
+                else if (PII_DIRECT_NAME_HINTS.has(lower)) {
                     // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
                     console.warn(`[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a PII-typical name but no personal annotation. If this is PII, mark it { personal: "self", find: ... }. If business data, set { personal: false, reason: "is_business_data" } to silence.`);
                 }

package/dist/engine/boot-validator/projection-list-screens.d.ts

@@ -1,4 +1,4 @@
-import type { FeatureDefinition, QueryHandlerDef } from "../types/index.js";
+import { type FeatureDefinition, type QueryHandlerDef } from "../types/index.js";
 export declare function buildQueryHandlerMap(features: readonly FeatureDefinition[]): ReadonlyMap<string, QueryHandlerDef>;
 export declare function validateProjectionListScreens(features: readonly FeatureDefinition[]): void;
 export declare function validateRelatedListSectionQueries(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/projection-list-screens.js

@@ -1,6 +1,7 @@
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
 import { parseQn, QnTypes, qualifyEntityName } from "../qualified-name.js";
 import { isEditLayoutScreen } from "../screen-helpers.js";
+import { relatedListGroupHeaderLabel, relatedListGroupKey, } from "../types/index.js";
 import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens.js";
 import { findEntity } from "./parent-ref.js";
 import { getZodObjectShape } from "./zod-shape.js";
@@ -198,6 +199,17 @@ function validateRelatedListParentFilter(prefix, section, schema, handler, featu
             `entity behind query "${section.query}". Known fields: ${Object.keys(entity.fields).sort().join(", ")}.`);
     }
 }
+// A collapsed group without a header has no toggle, so its rows could never be opened.
+function validateRelatedListGroupBy(prefix, section) {
+    const groupBy = section.groupBy;
+    const collapsedKey = groupBy?.collapsedWhen === undefined ? undefined : relatedListGroupKey(groupBy.collapsedWhen);
+    if (groupBy !== undefined &&
+        collapsedKey !== undefined &&
+        relatedListGroupHeaderLabel(groupBy, collapsedKey) === undefined) {
+        throw new Error(`${prefix}: groupBy.collapsedWhen "${collapsedKey}" names a group without a header; ` +
+            `set groupBy.label or groupBy.labels["${collapsedKey}"], or drop collapsedWhen.`);
+    }
+}
 // relatedList sections declare search/facets the same way a projectionList
 // screen does, and hit the same 422 footgun: definePagedQueryHandler doesn't
 // auto-merge params into the handler's own Zod schema (fw#2165/#2224), so an
@@ -214,6 +226,7 @@ export function validateRelatedListSectionQueries(features) {
         validateRelatedListSearchable(prefix, section, schema);
         validateRelatedListFacets(prefix, section, schema);
         validateRelatedListParentFilter(prefix, section, schema, handler, featureMap);
+        validateRelatedListGroupBy(prefix, section);
     };
     for (const feature of features) {
         for (const screen of Object.values(feature.screens)) {

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

@@ -620,6 +620,15 @@ function validateRedirectTarget(feature, screenId, screenKind, redirect, allScre
     }
     validateScreenNavTarget(feature.name, screenId, screenKind, "redirect", redirectTarget, allScreenQns, feature.screens);
 }
+// redirect is only honored on record actions; on list/related-list row
+// actions it would be silently dropped, so the author would believe it works.
+function rejectRedirectOnListRowAction(featureName, screenId, screenKind, action) {
+    if (action.kind !== "navigate" && action.kind !== "drawer" && action.redirect !== undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) rowAction "${action.id}" sets redirect — ` +
+            `redirect is only honored on record actions (projectionDetail/entityEdit header and section ` +
+            `actions) and is ignored on list row actions. Remove it.`);
+    }
+}
 // A writeHandler record action's redirect (projectionDetail/entityEdit
 // header and section actions) follows the entityEdit.redirect rule.
 function validateRecordActionRedirect(feature, screenId, screenKind, action, allScreenQns) {
@@ -780,6 +789,7 @@ function validateRelatedListSection(args) {
 function validateRelatedListRowActions(args, rowActions) {
     const { featureName, screenId, screenType, where, section, screens, allWriteHandlerQns, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens, } = args;
     for (const action of rowActions) {
+        rejectRedirectOnListRowAction(featureName, screenId, screenType, action);
         if (action.kind === "navigate") {
             const target = resolveRowActionNavigateTarget(featureName, screenId, screenType, "rowAction", action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens);
             validateRowActionNavigateParams(featureName, screenId, screenType, undefined, action, target);
@@ -899,6 +909,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             }
             if (screen.rowActions !== undefined) {
                 for (const action of screen.rowActions) {
+                    rejectRedirectOnListRowAction(feature.name, screenId, "projectionList", action);
                     if (action.kind === "navigate") {
                         const target = resolveRowActionNavigateTarget(feature.name, screenId, "projectionList", "rowAction", action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens);
                         validateRowActionNavigateParams(feature.name, screenId, "projectionList", undefined, action, target);
@@ -1414,6 +1425,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             // erst beim ersten Klick als "Screen not found" / 404 auf.
             if (screen.rowActions !== undefined) {
                 for (const action of screen.rowActions) {
+                    rejectRedirectOnListRowAction(feature.name, screenId, "entityList", action);
                     if (action.kind === "navigate") {
                         const target = resolveRowActionNavigateTarget(feature.name, screenId, "entityList", "rowAction", action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens);
                         // The renderer's default-entityId fallback (row["id"]) only fires

package/dist/engine/build-config-feature-schema.js

@@ -409,6 +409,7 @@ function buildSecretsEditScreen(screenId, secrets, access, declaredTranslationKe
     const fieldLabels = {};
     const fieldHints = {};
     const requiredFields = [];
+    const fieldAccess = {};
     // Mutable outer record — TranslationKeys' Readonly<Record<...>> index
     // signature only permits reading, so the top-level assignments below
     // need a writable local type; each entry is still a fresh, never-mutated object.
@@ -430,6 +431,8 @@ function buildSecretsEditScreen(screenId, secrets, access, declaredTranslationKe
             }
             if (s.def.required === true)
                 requiredFields.push(fieldId);
+            if (s.def.writeRoles !== undefined)
+                fieldAccess[fieldId] = { roles: [...s.def.writeRoles] };
         }
         const titleKey = `${feature}.settings`;
         sections.push({
@@ -444,6 +447,7 @@ function buildSecretsEditScreen(screenId, secrets, access, declaredTranslationKe
         fieldLabels,
         ...(Object.keys(fieldHints).length > 0 && { fieldHints }),
         ...(requiredFields.length > 0 && { requiredFields }),
+        ...(Object.keys(fieldAccess).length > 0 && { fieldAccess }),
         sections,
         ...(access !== undefined && { access }),
     };

package/dist/engine/config-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { ConfigBacking, ConfigBounds, ConfigComputedFn, ConfigKeyDefinition, ConfigKeyType, ConfigMask, ConfigSeedDef, ConfigValue, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, OptionsQueryPayload } from "./types/index.js";
+import type { ConfigBacking, ConfigBounds, ConfigComputedFn, ConfigKeyDefinition, ConfigKeyType, ConfigMask, ConfigSeedDef, ConfigValidateFn, ConfigValue, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, OptionsQueryPayload } from "./types/index.js";
 export declare function isEncryptedAtRest(def: Pick<ConfigKeyDefinition, "encrypted" | "backing">): boolean;
 export declare const access: {
     readonly all: readonly string[];
@@ -26,6 +26,7 @@ type ConfigKeyOptions<T extends ConfigKeyType> = {
         flags?: string;
     } : never;
     computed?: ConfigComputedFn<T>;
+    validate?: ConfigValidateFn<T>;
     allowPerRequest?: T extends "text" ? never : boolean;
     required?: boolean;
     env?: string;

package/dist/engine/config-helpers.js

@@ -60,6 +60,7 @@ function createConfigKey(scope, type, opts = {}) {
         bounds: opts.bounds, // @cast-boundary schema-walk
         ...(opts.pattern ? { pattern: opts.pattern } : {}),
         computed: opts.computed,
+        validate: opts.validate,
         ...(opts.allowPerRequest === true ? { allowPerRequest: true } : {}),
         ...(opts.required === true ? { required: true } : {}),
         ...(opts.env ? { env: opts.env } : {}),

package/dist/engine/define-feature.js

@@ -124,6 +124,7 @@ export function defineFeature(name, setup, settings) {
         handlerEntityMappings: state.handlerEntityMappings,
         metrics: state.metrics,
         secretKeys: state.secretKeys,
+        secretNamespaces: state.secretNamespaces,
         projections: state.projections,
         entityProjectionExtensions: state.entityProjectionExtensions,
         multiStreamProjections: state.multiStreamProjections,

package/dist/engine/extensions/escape-hatch-usage.js

@@ -7,6 +7,8 @@ export function extensionUsageEscapeHatchReason(usage) {
     const escapeHatch = usage.options?.["escapeHatch"];
     if (typeof escapeHatch !== "object" || escapeHatch === null)
         return undefined;
-    const reason = escapeHatch.reason;
+    const { reason, grants } = escapeHatch;
+    if (Array.isArray(grants) && !grants.includes("unsafeRaw"))
+        return undefined;
     return typeof reason === "string" && reason.trim().length > 0 ? reason : undefined;
 }

package/dist/engine/feature-ast/extractors/hooks.js

@@ -1,3 +1,4 @@
+import { isEscapeHatchGrant } from "@cosmicdrift/kumiko-types/handlers";
 import { SyntaxKind } from "ts-morph";
 import { sourceLocationFromNode } from "../source-location.js";
 import { containsRawRefSentinel, fail, findFunctionLiteral, isPlainObject, ok, readDataLiteralNode, readNameLiteral, readNameOrRef, readNameOrRefOrList, readObjectPropertyInitializer, } from "./shared.js";
@@ -75,7 +76,12 @@ export function readOptionalEscapeHatch(value) {
         return undefined;
     if (typeof value["reason"] !== "string")
         return undefined;
-    return { reason: value["reason"] };
+    const grants = value["grants"];
+    if (grants === undefined)
+        return { reason: value["reason"] };
+    if (!Array.isArray(grants) || !grants.every(isEscapeHatchGrant))
+        return undefined;
+    return { reason: value["reason"], grants };
 }
 // Reads the `escapeHatch` sub-property node first, not via readDataLiteralNode
 // on the whole object: a sibling property like `handler` (a closure) isn't

package/dist/engine/feature-ast/extractors/index.d.ts

@@ -7,7 +7,7 @@ export { collectScreenOpaqueProps, extractMultiStreamProjection, extractProjecti
 export { findImportBindingForLocalName, resolveModuleFile, } from "./resolve-import.js";
 export { extractDescribe, extractOptionalRequires, extractReadsConfig, extractRequires, extractSystemScope, extractToggleable, extractUiHints, } from "./round1.js";
 export { extractEntity, extractNav, extractRelation, extractWorkspace, } from "./round2.js";
-export { extractClaimKey, extractConfig, extractMetric, extractReferenceData, extractSecret, extractTranslations, extractUseExtension, isClaimKeyType, type NamedOptionsResult, readNamedOptions, } from "./round3.js";
+export { extractClaimKey, extractConfig, extractMetric, extractReferenceData, extractSecret, extractSecretNamespace, extractTranslations, extractUseExtension, isClaimKeyType, type NamedOptionsResult, readNamedOptions, } from "./round3.js";
 export { extractBootCheck, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractStoreTable, extractUsesApi, } from "./round5.js";
 export { extractTreeActions } from "./round6.js";
 export type { ExtractOutput } from "./shared.js";

package/dist/engine/feature-ast/extractors/index.js

@@ -7,7 +7,7 @@ export { collectScreenOpaqueProps, extractMultiStreamProjection, extractProjecti
 export { findImportBindingForLocalName, resolveModuleFile, } from "./resolve-import.js";
 export { extractDescribe, extractOptionalRequires, extractReadsConfig, extractRequires, extractSystemScope, extractToggleable, extractUiHints, } from "./round1.js";
 export { extractEntity, extractNav, extractRelation, extractWorkspace, } from "./round2.js";
-export { extractClaimKey, extractConfig, extractMetric, extractReferenceData, extractSecret, extractTranslations, extractUseExtension, isClaimKeyType, readNamedOptions, } from "./round3.js";
+export { extractClaimKey, extractConfig, extractMetric, extractReferenceData, extractSecret, extractSecretNamespace, extractTranslations, extractUseExtension, isClaimKeyType, readNamedOptions, } from "./round3.js";
 export { extractBootCheck, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractStoreTable, extractUsesApi, } from "./round5.js";
 export { extractTreeActions } from "./round6.js";
 export { fail, findFunctionLiteral, isPlainObject, ok, readBooleanProperty, readDataLiteralNode, readNameOrRef, readNameOrRefOrList, readObjectPropertyInitializer, readPropertyKey, readStringLiteralArgs, readVarargsOrArrayProp, resolveSameFileObjectLiteral, } from "./shared.js";

package/dist/engine/feature-ast/extractors/jobs-routes.js

@@ -126,10 +126,14 @@ export function extractHttpRoute(call, sourceFile) {
     if (!fn) {
         return fail("httpRoute", sourceLocationFromNode(call, sourceFile), "handler must be an inline arrow function or function expression");
     }
-    // Missing/non-boolean `anonymous` reads as false (the safe side — mounted
+    // Missing `anonymous` reads as false (the safe side — mounted
     // behind the session auth chain, not public) so a source file that predates
     // the required field still parses instead of erroring here.
-    const anonymous = readBooleanProperty(arg, "anonymous") === true;
+    const anonymousValue = readBooleanProperty(arg, "anonymous");
+    if (anonymousValue === undefined && arg.getProperty("anonymous") !== undefined) {
+        return fail("httpRoute", sourceLocationFromNode(call, sourceFile), "anonymous must be a boolean literal — a non-literal value would be rewritten to a literal on round-trip");
+    }
+    const anonymous = anonymousValue === true;
     return ok({
         kind: "httpRoute",
         source: sourceLocationFromNode(call, sourceFile),

package/dist/engine/feature-ast/extractors/round3.d.ts

@@ -1,7 +1,7 @@
 import type { CallExpression, SourceFile } from "ts-morph";
 import type { ClaimKeyType } from "../../types/handlers.js";
 import type { ParseError } from "../parse.js";
-import type { ClaimKeyPattern, ConfigPattern, MetricPattern, ReferenceDataPattern, SecretPattern, TranslationsPattern, UseExtensionPattern } from "../patterns.js";
+import type { ClaimKeyPattern, ConfigPattern, MetricPattern, ReferenceDataPattern, SecretNamespacePattern, SecretPattern, TranslationsPattern, UseExtensionPattern } from "../patterns.js";
 import { type ExtractOutput } from "./shared.js";
 export type NamedOptionsResult = {
     readonly kind: "ok";
@@ -16,6 +16,7 @@ export declare function extractConfig(call: CallExpression, sourceFile: SourceFi
 export declare function extractTranslations(call: CallExpression, sourceFile: SourceFile): ExtractOutput<TranslationsPattern>;
 export declare function extractMetric(call: CallExpression, sourceFile: SourceFile): ExtractOutput<MetricPattern>;
 export declare function extractSecret(call: CallExpression, sourceFile: SourceFile): ExtractOutput<SecretPattern>;
+export declare function extractSecretNamespace(call: CallExpression, sourceFile: SourceFile): ExtractOutput<SecretNamespacePattern>;
 export declare function isClaimKeyType(value: unknown): value is ClaimKeyType;
 export declare function extractClaimKey(call: CallExpression, sourceFile: SourceFile): ExtractOutput<ClaimKeyPattern>;
 export declare function extractReferenceData(call: CallExpression, sourceFile: SourceFile): ExtractOutput<ReferenceDataPattern>;

package/dist/engine/feature-ast/extractors/round3.js

@@ -98,6 +98,17 @@ export function extractSecret(call, sourceFile) {
         options: parsed.options,
     });
 }
+export function extractSecretNamespace(call, sourceFile) {
+    const parsed = readNamedOptions(call, sourceFile, "secretNamespace");
+    if (parsed.kind === "error")
+        return parsed;
+    return ok({
+        kind: "secretNamespace",
+        source: sourceLocationFromNode(call, sourceFile),
+        shortName: parsed.name,
+        options: parsed.options,
+    });
+}
 export function isClaimKeyType(value) {
     return (value === "string" ||
         value === "number" ||

package/dist/engine/feature-ast/extractors/shared.js

@@ -195,9 +195,7 @@ function resolveIdentifierToStringLiteral(identifier) {
     const scoped = findScopedVariableDeclaration(id, name);
     if (scoped) {
         const init = scoped.getInitializer();
-        const value = init ? unwrapLiteralInitializer(init) : undefined;
-        if (value !== undefined)
-            return value;
+        return init ? unwrapLiteralInitializer(init) : undefined;
     }
     const binding = findImportBindingForLocalName(id.getSourceFile(), name);
     if (!binding)

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

@@ -8,7 +8,7 @@ export type { AddAuthClaimsArgs, AddClaimKeyArgs, AddConfigArgs, AddDefineEventA
 export { createFeaturePatcher } from "./patcher.js";
 export type { PatternChangeIssue, PatternChangesParseResult } from "./pattern-change-schema.js";
 export { parsePatternChanges } from "./pattern-change-schema.js";
-export type { AuthClaimsPattern, ClaimKeyPattern, ConfigPattern, DefineEventPattern, Editability, EntityPattern, ExtendsRegistrarPattern, FeaturePattern, FeaturePatternKind, HookPattern, HttpRoutePattern, JobPattern, MetricPattern, MultiStreamProjectionPattern, NavPattern, NotificationPattern, OptionalRequiresPattern, ProjectionPattern, QueryHandlerPattern, ReadsConfigPattern, ReferenceDataPattern, RelationPattern, RequiresPattern, ScreenPattern, SecretPattern, StreamHandlerPattern, SystemScopePattern, ToggleablePattern, TranslationsPattern, UnknownPattern, UseExtensionPattern, WorkspacePattern, WriteHandlerPattern, } from "./patterns.js";
+export type { AuthClaimsPattern, ClaimKeyPattern, ConfigPattern, DefineEventPattern, Editability, EntityPattern, ExtendsRegistrarPattern, FeaturePattern, FeaturePatternKind, HookPattern, HttpRoutePattern, JobPattern, MetricPattern, MultiStreamProjectionPattern, NavPattern, NotificationPattern, OptionalRequiresPattern, ProjectionPattern, QueryHandlerPattern, ReadsConfigPattern, ReferenceDataPattern, RelationPattern, RequiresPattern, ScreenPattern, SecretNamespacePattern, SecretPattern, StreamHandlerPattern, SystemScopePattern, ToggleablePattern, TranslationsPattern, UnknownPattern, UseExtensionPattern, WorkspacePattern, WriteHandlerPattern, } from "./patterns.js";
 export { getEditability } from "./patterns.js";
 export type { RenderFeatureFileInput } from "./render.js";
 export { FEATURE_FILE_VERSION, renderFeatureFile, renderPattern, renderValue, VERSION_HEADER, } from "./render.js";

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

@@ -21,7 +21,7 @@
 // Per-pattern extractors fill in iteratively (C1.5) — each round adds
 // one extractor + a focused test.
 import { Project, SyntaxKind } from "ts-morph";
-import { extractAiClassify, extractAiExtract, extractAiGenerate, extractAuthClaims, extractBootCheck, extractClaimKey, extractConfig, extractDefineEvent, extractDescribe, extractEntity, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractHook, extractHttpRoute, extractJob, extractMetric, extractMultiStreamProjection, extractNav, extractNotification, extractOptionalRequires, extractProjection, extractQueryHandler, extractReadsConfig, extractReferenceData, extractRelation, extractRequires, extractScreen, extractSecret, extractStoreTable, extractStreamHandler, extractSystemScope, extractToggleable, extractTranslations, extractTreeActions, extractUiHints, extractUseExtension, extractUsesApi, extractWorkspace, extractWriteHandler, findFunctionLiteral, findImportBindingForLocalName, readObjectPropertyInitializer, resolveModuleFile, resolveSameFileObjectLiteral, } from "./extractors/index.js";
+import { extractAiClassify, extractAiExtract, extractAiGenerate, extractAuthClaims, extractBootCheck, extractClaimKey, extractConfig, extractDefineEvent, extractDescribe, extractEntity, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractHook, extractHttpRoute, extractJob, extractMetric, extractMultiStreamProjection, extractNav, extractNotification, extractOptionalRequires, extractProjection, extractQueryHandler, extractReadsConfig, extractReferenceData, extractRelation, extractRequires, extractScreen, extractSecret, extractSecretNamespace, extractStoreTable, extractStreamHandler, extractSystemScope, extractToggleable, extractTranslations, extractTreeActions, extractUiHints, extractUseExtension, extractUsesApi, extractWorkspace, extractWriteHandler, findFunctionLiteral, findImportBindingForLocalName, readObjectPropertyInitializer, resolveModuleFile, resolveSameFileObjectLiteral, } from "./extractors/index.js";
 import { sourceLocationFromNode } from "./source-location.js";
 /**
  * Parse the given feature file and return all recognised r.* calls
@@ -415,6 +415,8 @@ function dispatchExtractor(methodName, call, sourceFile) {
             return extractMetric(call, sourceFile);
         case "secret":
             return extractSecret(call, sourceFile);
+        case "secretNamespace":
+            return extractSecretNamespace(call, sourceFile);
         case "claimKey":
             return extractClaimKey(call, sourceFile);
         case "referenceData":

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

@@ -44,6 +44,9 @@ export type PatternId = {
 } | {
     readonly kind: "secret";
     readonly shortName: string;
+} | {
+    readonly kind: "secretNamespace";
+    readonly shortName: string;
 } | {
     readonly kind: "claimKey";
     readonly shortName: string;

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

@@ -85,9 +85,7 @@ export function applyChanges(sourceFile, changes) {
  * biome-stable formatting that matches the renderFeatureFile output.
  */
 export function addPattern(sourceFile, pattern) {
-    if (pattern.kind === "ai.generate" ||
-        pattern.kind === "ai.extract" ||
-        pattern.kind === "ai.classify") {
+    if (isAiStepId(pattern)) {
         throw new Error(`addPattern: ${pattern.kind} steps must be inserted into a defineWorkflow steps array, not the setup body`);
     }
     const setup = findSetupCallback(sourceFile);
@@ -430,11 +428,10 @@ function applyEditsDescending(sourceFile, edits) {
     for (const edit of sorted)
         sourceFile.replaceText([edit.start, edit.end], edit.text);
 }
-// =============================================================================
-// Lookup
-// =============================================================================
-function isAiStepId(id) {
-    return id.kind === "ai.generate" || id.kind === "ai.extract" || id.kind === "ai.classify";
+function isAiStepId(idOrPattern) {
+    return (idOrPattern.kind === "ai.generate" ||
+        idOrPattern.kind === "ai.extract" ||
+        idOrPattern.kind === "ai.classify");
 }
 function aiStepPatchSpan(sourceFile, call) {
     const start = call.getStart();
@@ -503,7 +500,7 @@ export const SINGLETON_KINDS = new Set([
  * feature can fix it explicitly.
  */
 function findCallForId(sourceFile, id) {
-    if (id.kind === "ai.generate" || id.kind === "ai.extract" || id.kind === "ai.classify") {
+    if (isAiStepId(id)) {
         return findAiStepCall(sourceFile, id);
     }
     const setup = findSetupCallback(sourceFile);
@@ -561,9 +558,8 @@ function readAiStepKey(call) {
     return undefined;
 }
 function findAiStepCall(sourceFile, id) {
-    if (id.kind !== "ai.generate" && id.kind !== "ai.extract" && id.kind !== "ai.classify") {
+    if (!isAiStepId(id))
         return undefined;
-    }
     const factory = AI_STEP_FACTORY[id.kind];
     const matches = [];
     for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
@@ -629,6 +625,7 @@ function callMatchesId(call, id) {
                 matchObjectProperty(call, "target", id.target));
         case "metric":
         case "secret":
+        case "secretNamespace":
         case "claimKey":
             return (matchFirstArgString(call, id.shortName) || matchObjectProperty(call, "name", id.shortName));
         case "referenceData":

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

@@ -1,7 +1,7 @@
 import type { SourceFile } from "ts-morph";
 import type { LifecycleHookType } from "../constants.js";
 import type { ConfigKeyDefinition, ConfigKeyType, JobDefinition, RunIn, TranslationKeys } from "../types/config.js";
-import type { MetricOptions, SecretOptions } from "../types/feature.js";
+import type { MetricOptions, SecretNamespaceOptions, SecretOptions } from "../types/feature.js";
 import type { EntityDefinition } from "../types/fields.js";
 import type { AccessRule, ClaimKeyType, EscapeHatchDeclaration, RateLimitOption } from "../types/handlers.js";
 import type { HookPhase } from "../types/hooks.js";
@@ -115,6 +115,10 @@ export type AddSecretArgs = {
     readonly name: string;
     readonly options: SecretOptions;
 };
+export type AddSecretNamespaceArgs = {
+    readonly name: string;
+    readonly options: SecretNamespaceOptions;
+};
 export type AddClaimKeyArgs = {
     readonly name: string;
     readonly type: ClaimKeyType;
@@ -177,6 +181,7 @@ export type FeaturePatcher = {
     readonly addTranslations: (args: AddTranslationsArgs) => void;
     readonly addMetric: (args: AddMetricArgs) => void;
     readonly addSecret: (args: AddSecretArgs) => void;
+    readonly addSecretNamespace: (args: AddSecretNamespaceArgs) => void;
     readonly addClaimKey: (args: AddClaimKeyArgs) => void;
     readonly addReferenceData: (args: AddReferenceDataArgs) => void;
     readonly addUseExtension: (args: AddUseExtensionArgs) => void;