@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/engine/feature-ast/pattern-id-matchers.js

@@ -0,0 +1,210 @@
+import { SyntaxKind } from "ts-morph";
+import { readNameLiteral, readNameOrRef, resolveSameFileObjectLiteral, } from "./extractors/shared.js";
+const PATTERN_ID_MATCHERS = {
+    requires: matchSingletonCall,
+    optionalRequires: matchSingletonCall,
+    readsConfig: matchSingletonCall,
+    systemScope: matchSingletonCall,
+    toggleable: matchSingletonCall,
+    describe: matchSingletonCall,
+    uiHints: matchSingletonCall,
+    config: matchSingletonCall,
+    translations: matchSingletonCall,
+    authClaims: matchSingletonCall,
+    treeActions: matchSingletonCall,
+    entity: matchEntityCall,
+    relation: matchRelationCall,
+    nav: matchIdPropertyCall,
+    workspace: matchIdPropertyCall,
+    screen: matchIdPropertyCall,
+    writeHandler: matchHandlerCall,
+    queryHandler: matchHandlerCall,
+    streamHandler: matchHandlerCall,
+    hook: matchHookCall,
+    metric: matchShortNameCall,
+    secret: matchShortNameCall,
+    secretNamespace: matchShortNameCall,
+    claimKey: matchShortNameCall,
+    referenceData: matchReferenceDataCall,
+    useExtension: matchUseExtensionCall,
+    job: matchJobCall,
+    notification: matchNotificationCall,
+    httpRoute: matchHttpRouteCall,
+    projection: matchProjectionCall,
+    multiStreamProjection: matchProjectionCall,
+    defineEvent: matchDefineEventCall,
+    extendsRegistrar: matchExtendsRegistrarCall,
+    "ai.generate": matchAiStepCall,
+    "ai.extract": matchAiStepCall,
+    "ai.classify": matchAiStepCall,
+};
+export function callMatchesId(call, kind, id) {
+    return PATTERN_ID_MATCHERS[kind](call, id);
+}
+// Singletons: kind alone identifies the call.
+function matchSingletonCall() {
+    return true;
+}
+function matchEntityCall(call, id) {
+    return (matchFirstArgString(call, id.entityName) || matchObjectProperty(call, "name", id.entityName));
+}
+// Positional: r.relation(entity, name, def) | Object: { entity, name, ... }
+function matchRelationCall(call, id) {
+    if (matchFirstArgString(call, id.entityName)) {
+        return matchArgString(call, 1, id.relationName);
+    }
+    return (matchObjectProperty(call, "entity", id.entityName) &&
+        matchObjectProperty(call, "name", id.relationName));
+}
+function matchIdPropertyCall(call, id) {
+    return matchObjectProperty(call, "id", id.id);
+}
+function matchHandlerCall(call, id) {
+    return (matchFirstArgString(call, id.handlerName) || matchObjectProperty(call, "name", id.handlerName));
+}
+// Positional: r.hook(type, target, fn) | Object: { type, target }
+function matchHookCall(call, id) {
+    if (typeof id.target === "object") {
+        return matchHookAllOfCall(call, id.hookType, id.target.allOf);
+    }
+    if (matchFirstArgString(call, id.hookType)) {
+        return matchArgNameOrRef(call, 1, id.target);
+    }
+    return (matchObjectProperty(call, "type", id.hookType) && matchObjectProperty(call, "target", id.target));
+}
+// Entity-wide { allOf } target — only ever appears as the object
+// literal { allOf: entity } (positional or nested in the object
+// form), never as a bare string, so check both call shapes.
+function matchHookAllOfCall(call, hookType, allOfEntity) {
+    if (matchFirstArgString(call, hookType)) {
+        return matchAllOfArg(call.getArguments()[1], allOfEntity);
+    }
+    return (matchObjectProperty(call, "type", hookType) &&
+        matchObjectAllOfProperty(call, "target", allOfEntity));
+}
+function matchShortNameCall(call, id) {
+    return matchFirstArgString(call, id.shortName) || matchObjectProperty(call, "name", id.shortName);
+}
+function matchReferenceDataCall(call, id) {
+    return (matchFirstArgString(call, id.entityName) || matchObjectProperty(call, "entity", id.entityName));
+}
+// Positional: r.useExtension(name, entity) | Object: { name, entity }
+function matchUseExtensionCall(call, id) {
+    if (matchFirstArgString(call, id.extensionName)) {
+        return matchArgNameOrRef(call, 1, id.entityName);
+    }
+    return (matchObjectProperty(call, "name", id.extensionName) &&
+        matchObjectProperty(call, "entity", id.entityName));
+}
+function matchJobCall(call, id) {
+    return matchFirstArgString(call, id.jobName) || matchObjectProperty(call, "name", id.jobName);
+}
+function matchNotificationCall(call, id) {
+    return (matchFirstArgString(call, id.notificationName) ||
+        matchObjectProperty(call, "name", id.notificationName));
+}
+// Object form only; positional doesn't apply.
+function matchHttpRouteCall(call, id) {
+    return (matchObjectProperty(call, "method", id.method) && matchObjectProperty(call, "path", id.path));
+}
+function matchProjectionCall(call, id) {
+    return matchObjectProperty(call, "name", id.name);
+}
+function matchDefineEventCall(call, id) {
+    return matchFirstArgString(call, id.eventName) || matchObjectProperty(call, "name", id.eventName);
+}
+function matchExtendsRegistrarCall(call, id) {
+    return matchFirstArgString(call, id.extensionName);
+}
+function matchAiStepCall(call, id) {
+    return readAiStepKey(call) === id.stepKey;
+}
+function readAiStepKey(call) {
+    const arg = call.getArguments()[0];
+    if (!arg)
+        return undefined;
+    const obj = resolveSameFileObjectLiteral(arg);
+    if (!obj)
+        return undefined;
+    const prop = obj.getProperty("stepKey");
+    if (!prop)
+        return undefined;
+    const assign = prop.asKind(SyntaxKind.PropertyAssignment);
+    if (assign) {
+        const init = assign.getInitializer();
+        if (!init)
+            return undefined;
+        return readNameLiteral(init);
+    }
+    const shorthand = prop.asKind(SyntaxKind.ShorthandPropertyAssignment);
+    if (shorthand)
+        return readNameLiteral(shorthand.getNameNode());
+    return undefined;
+}
+// Resolves an argument the same way the extractors do (readNameLiteral):
+// a string literal directly, or a bare identifier following its
+// declaration (same-file or imported) to a string-literal initializer —
+// the dominant naming style in the framework's own bundled-features
+// (`r.entity(ENTITY, ...)`, `r.useExtension(EXT_X, ...)`).
+//
+// Narrow on purpose: every kind's arg-0 (and relation's arg-1) is parsed
+// via readNameLiteral, never readNameOrRef (see round2.ts/round3.ts) —
+// widening this shared helper to readNameOrRef would let an object-form
+// call's first argument (an ObjectLiteralExpression) match here too,
+// short-circuiting the object-form branch in callMatchesId. Positions
+// where the parser itself accepts an inline `{ name: "..." }` ref use
+// `matchArgNameOrRef` below instead.
+function matchArgString(call, index, expected) {
+    const arg = call.getArguments()[index];
+    if (!arg)
+        return false;
+    return readNameLiteral(arg) === expected;
+}
+// @wrapper-known semantic-alias
+function matchFirstArgString(call, expected) {
+    return matchArgString(call, 0, expected);
+}
+// Like matchArgString, but via readNameOrRef — for the specific positional
+// slots where the parser accepts an inline `{ name: "..." }` object ref in
+// addition to a literal/identifier (useExtension's entity arg, hook's
+// target arg; see round3.ts:445 / hooks.ts:75). Not a drop-in replacement
+// for matchArgString: applying it to an arg-0 position would match an
+// object-form call's first (and only) argument, see the comment above.
+function matchArgNameOrRef(call, index, expected) {
+    const arg = call.getArguments()[index];
+    if (!arg)
+        return false;
+    return readNameOrRef(arg) === expected;
+}
+// Object-form property values are resolved via readNameOrRef, not the
+// narrower readNameLiteral — some properties (useExtension's `entity`,
+// hook's `target`/`allOf`) accept an inline `{ name: "..." }` ref in the
+// parser (see extractors/round3.ts, extractors/hooks.ts), not just a
+// literal or identifier. readNameOrRef is a superset of readNameLiteral,
+// so this is safe for every other property too.
+function matchObjectProperty(call, propName, expected) {
+    const obj = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
+    if (!obj)
+        return false;
+    const init = obj.getProperty(propName)?.asKind(SyntaxKind.PropertyAssignment)?.getInitializer();
+    if (!init)
+        return false;
+    return readNameOrRef(init) === expected;
+}
+// Matches an r.hook `{ allOf: entity }` target — as the arg node directly
+// (positional call form) or as a nested object property (object call form).
+function matchAllOfArg(node, expectedEntity) {
+    const obj = node?.asKind(SyntaxKind.ObjectLiteralExpression);
+    const init = obj?.getProperty("allOf")?.asKind(SyntaxKind.PropertyAssignment)?.getInitializer();
+    if (!init)
+        return false;
+    return readNameOrRef(init) === expectedEntity;
+}
+function matchObjectAllOfProperty(call, propName, expectedEntity) {
+    const obj = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
+    const propInit = obj
+        ?.getProperty(propName)
+        ?.asKind(SyntaxKind.PropertyAssignment)
+        ?.getInitializer();
+    return matchAllOfArg(propInit, expectedEntity);
+}

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

@@ -18,6 +18,7 @@ export type EntityPattern = {
     readonly source: SourceLocation;
     readonly entityName: string;
     readonly definition: EntityDefinition;
+    readonly backingTable?: RawRefSentinel;
 };
 export type RelationPattern = {
     readonly kind: "relation";
@@ -258,14 +259,14 @@ export type EnvSchemaPattern = {
     readonly source: SourceLocation;
     readonly schemaBody: SourceLocation;
 };
-/** Live-editable policy defaults for an AI pipeline step instance (#256). */
+/** Live-editable policy defaults for an AI pipeline step instance. */
 export type AiStepPolicy = {
     readonly enabled: boolean;
     readonly providerId?: string;
     readonly model?: string;
     readonly params: Record<string, unknown>;
 };
-/** Preserves an unresolvable argument reference across parse → render (#998). */
+/** Preserves an unresolvable argument reference across parse → render. */
 export type AiStepOpaqueArgs = {
     readonly __raw: string;
 };
@@ -304,6 +305,14 @@ export type UnknownPattern = {
 };
 export type FeaturePattern = EntityPattern | RelationPattern | NavPattern | WorkspacePattern | ConfigPattern | TranslationsPattern | RequiresPattern | OptionalRequiresPattern | SystemScopePattern | ToggleablePattern | DescribePattern | UiHintsPattern | MetricPattern | SecretPattern | SecretNamespacePattern | ClaimKeyPattern | ReferenceDataPattern | ReadsConfigPattern | UseExtensionPattern | UsesApiPattern | ExposesApiPattern | TreeActionsPattern | ScreenPattern | WriteHandlerPattern | QueryHandlerPattern | StreamHandlerPattern | HookPattern | JobPattern | NotificationPattern | AuthClaimsPattern | HttpRoutePattern | ProjectionPattern | MultiStreamProjectionPattern | DefineEventPattern | ExtendsRegistrarPattern | EnvSchemaPattern | AiGeneratePattern | AiExtractPattern | AiClassifyPattern | UnknownPattern;
 export type FeaturePatternKind = FeaturePattern["kind"];
+export type MembersByKind<U extends {
+    readonly kind: string;
+}> = {
+    readonly [K in U["kind"]]: Extract<U, {
+        readonly kind: K;
+    }>;
+};
+export type FeaturePatternOfKind = MembersByKind<FeaturePattern>;
 export type Editability = "static" | "mixed" | "opaque";
 export declare function getEditability(pattern: FeaturePattern): Editability;
 export {};

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

@@ -59,56 +59,48 @@
 // against this constant to decide "form vs read-only span" — the actual
 // SourceLocation lives at the matching path in `opaqueProps`.
 export const SCREEN_OPAQUE_MARKER = "$opaque";
+const EDITABILITY_BY_KIND = {
+    entity: "static",
+    relation: "static",
+    nav: "static",
+    workspace: "static",
+    config: "static",
+    translations: "static",
+    requires: "static",
+    optionalRequires: "static",
+    systemScope: "static",
+    toggleable: "static",
+    describe: "static",
+    metric: "static",
+    secret: "static",
+    secretNamespace: "static",
+    claimKey: "static",
+    referenceData: "static",
+    readsConfig: "static",
+    useExtension: "static",
+    usesApi: "static",
+    exposesApi: "static",
+    treeActions: "static",
+    screen: "mixed",
+    writeHandler: "mixed",
+    queryHandler: "mixed",
+    streamHandler: "mixed",
+    hook: "mixed",
+    job: "mixed",
+    notification: "mixed",
+    httpRoute: "mixed",
+    projection: "mixed",
+    multiStreamProjection: "mixed",
+    defineEvent: "mixed",
+    "ai.generate": "mixed",
+    "ai.extract": "mixed",
+    "ai.classify": "mixed",
+    authClaims: "opaque",
+    extendsRegistrar: "opaque",
+    envSchema: "opaque",
+    uiHints: "opaque",
+    unknown: "opaque",
+};
 export function getEditability(pattern) {
-    switch (pattern.kind) {
-        case "entity":
-        case "relation":
-        case "nav":
-        case "workspace":
-        case "config":
-        case "translations":
-        case "requires":
-        case "optionalRequires":
-        case "systemScope":
-        case "toggleable":
-        case "describe":
-        case "metric":
-        case "secret":
-        case "secretNamespace":
-        case "claimKey":
-        case "referenceData":
-        case "readsConfig":
-        case "useExtension":
-        case "usesApi":
-        case "exposesApi":
-        case "treeActions":
-            return "static";
-        case "screen":
-        case "writeHandler":
-        case "queryHandler":
-        case "streamHandler":
-        case "hook":
-        case "job":
-        case "notification":
-        case "httpRoute":
-        case "projection":
-        case "multiStreamProjection":
-        case "defineEvent":
-        case "ai.generate":
-        case "ai.extract":
-        case "ai.classify":
-            return "mixed";
-        case "authClaims":
-        case "extendsRegistrar":
-        case "envSchema":
-        case "uiHints":
-        case "unknown":
-            return "opaque";
-        default: {
-            // Exhaustiveness guard — adding a new pattern kind without
-            // updating this switch produces a compile error here.
-            const _exhaustive = pattern;
-            return _exhaustive;
-        }
-    }
+    return EDITABILITY_BY_KIND[pattern.kind];
 }

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

@@ -30,92 +30,52 @@ export const VERSION_HEADER = `// kumiko-feature-version: ${FEATURE_FILE_VERSION
  * trailing newline; callers compose statements with their own joiner.
  */
 export function renderPattern(pattern) {
-    switch (pattern.kind) {
-        case "requires":
-            return renderRequires(pattern);
-        case "optionalRequires":
-            return renderOptionalRequires(pattern);
-        case "readsConfig":
-            return renderReadsConfig(pattern);
-        case "systemScope":
-            return renderSystemScope(pattern);
-        case "toggleable":
-            return renderToggleable(pattern);
-        case "describe":
-            return renderDescribe(pattern);
-        case "uiHints":
-            return renderUiHints(pattern);
-        case "entity":
-            return renderEntity(pattern);
-        case "relation":
-            return renderRelation(pattern);
-        case "nav":
-            return renderNav(pattern);
-        case "workspace":
-            return renderWorkspace(pattern);
-        case "config":
-            return renderConfig(pattern);
-        case "translations":
-            return renderTranslations(pattern);
-        case "metric":
-            return renderMetric(pattern);
-        case "secret":
-            return renderSecret(pattern);
-        case "secretNamespace":
-            return renderSecretNamespace(pattern);
-        case "claimKey":
-            return renderClaimKey(pattern);
-        case "referenceData":
-            return renderReferenceData(pattern);
-        case "useExtension":
-            return renderUseExtension(pattern);
-        case "screen":
-            return renderScreen(pattern);
-        case "writeHandler":
-            return renderWriteHandler(pattern);
-        case "queryHandler":
-            return renderQueryHandler(pattern);
-        case "streamHandler":
-            return renderStreamHandler(pattern);
-        case "hook":
-            return renderHook(pattern);
-        case "job":
-            return renderJob(pattern);
-        case "notification":
-            return renderNotification(pattern);
-        case "authClaims":
-            return renderAuthClaims(pattern);
-        case "httpRoute":
-            return renderHttpRoute(pattern);
-        case "projection":
-            return renderProjection(pattern);
-        case "multiStreamProjection":
-            return renderMultiStreamProjection(pattern);
-        case "defineEvent":
-            return renderDefineEvent(pattern);
-        case "extendsRegistrar":
-            return renderExtendsRegistrar(pattern);
-        case "usesApi":
-            return renderUsesApi(pattern);
-        case "exposesApi":
-            return renderExposesApi(pattern);
-        case "treeActions":
-            return renderTreeActions(pattern);
-        case "envSchema":
-            return renderEnvSchema(pattern);
-        case "ai.generate":
-            return renderAiGenerate(pattern);
-        case "ai.extract":
-            return renderAiExtract(pattern);
-        case "ai.classify":
-            return renderAiClassify(pattern);
-        case "unknown":
-            return renderUnknown(pattern);
-        default: {
-            const _exhaustive = pattern;
-            return _exhaustive;
-        }
-    }
+    return renderPatternOfKind(pattern.kind, pattern);
+}
+const PATTERN_RENDERERS = {
+    requires: renderRequires,
+    optionalRequires: renderOptionalRequires,
+    readsConfig: renderReadsConfig,
+    systemScope: renderSystemScope,
+    toggleable: renderToggleable,
+    describe: renderDescribe,
+    uiHints: renderUiHints,
+    entity: renderEntity,
+    relation: renderRelation,
+    nav: renderNav,
+    workspace: renderWorkspace,
+    config: renderConfig,
+    translations: renderTranslations,
+    metric: renderMetric,
+    secret: renderSecret,
+    secretNamespace: renderSecretNamespace,
+    claimKey: renderClaimKey,
+    referenceData: renderReferenceData,
+    useExtension: renderUseExtension,
+    screen: renderScreen,
+    writeHandler: renderWriteHandler,
+    queryHandler: renderQueryHandler,
+    streamHandler: renderStreamHandler,
+    hook: renderHook,
+    job: renderJob,
+    notification: renderNotification,
+    authClaims: renderAuthClaims,
+    httpRoute: renderHttpRoute,
+    projection: renderProjection,
+    multiStreamProjection: renderMultiStreamProjection,
+    defineEvent: renderDefineEvent,
+    extendsRegistrar: renderExtendsRegistrar,
+    usesApi: renderUsesApi,
+    exposesApi: renderExposesApi,
+    treeActions: renderTreeActions,
+    envSchema: renderEnvSchema,
+    "ai.generate": renderAiGenerate,
+    "ai.extract": renderAiExtract,
+    "ai.classify": renderAiClassify,
+    unknown: renderUnknown,
+};
+function renderPatternOfKind(kind, pattern) {
+    return PATTERN_RENDERERS[kind](pattern);
 }
 // =============================================================================
 // JSON-Like Value Renderer — emits TypeScript-source-compatible literals.
@@ -206,7 +166,8 @@ function renderEntity(p) {
     // losing `name` to the sentinel shortcut — spread the reference verbatim
     // next to the name instead.
     if (isRawRefSentinel(p.definition)) {
-        return `r.entity({ name: ${JSON.stringify(p.entityName)}, ...${p.definition.__raw} });`;
+        const backingTable = p.backingTable ? `, backingTable: ${p.backingTable.__raw}` : "";
+        return `r.entity({ name: ${JSON.stringify(p.entityName)}, ...${p.definition.__raw}${backingTable} });`;
     }
     const merged = { name: p.entityName, ...p.definition };
     return `r.entity(${renderValue(merged)});`;
@@ -278,7 +239,7 @@ function renderUseExtension(p) {
     if (p.extensionNameRaw !== undefined) {
         // A raw-ref name can't be spread into the merged Object-Form without
         // losing it to renderValue's plain-string serialization — fall back
-        // to positional form, which keeps the reference verbatim (#2111).
+        // to positional form, which keeps the reference verbatim.
         const optionsArg = p.options !== undefined ? `, ${renderValue(p.options)}` : "";
         return `r.useExtension(${nameLiteral}, ${JSON.stringify(p.entityName)}${optionsArg});`;
     }
@@ -568,7 +529,7 @@ function renderMultiStreamProjection(p) {
 function renderDefineEvent(p) {
     const nameLiteral = p.eventNameRaw ?? JSON.stringify(p.eventName);
     const migrationEntries = p.migrations !== undefined ? Object.entries(p.migrations) : [];
-    // piiFields is a mandatory option (fw#2558) — the options object is
+    // piiFields is a mandatory option — the options object is
     // always rendered, unlike the old version/migrations-only shortcut.
     const lines = [`r.defineEvent(${nameLiteral}, ${p.schemaSource.raw}, {`];
     lines.push(`  piiFields: ${p.piiFields.raw},`);

package/dist/engine/feature-config-events-jobs.js

@@ -4,7 +4,7 @@ import { isValidIanaTimeZone } from "../time/iana.js";
 import { reasonProblem } from "./escape-hatch-reason.js";
 import { createEventDef } from "./event-def.js";
 import { resolveName } from "./handler-helpers.js";
-import { splitNamedDefinition, unwrapArrayForm } from "./object-form.js";
+import { requireArgument, splitNamedDefinition, unwrapArrayForm } from "./object-form.js";
 import { QnTypes, qn, toKebab } from "./qualified-name.js";
 // Builds config/secrets/claims/events/jobs/notifications registrar methods.
 export function buildConfigEventsJobsMethods(state, name) {
@@ -49,7 +49,7 @@ export function buildConfigEventsJobsMethods(state, name) {
     }
     // Shared by defineEvent's `migrations` option — each entry registers a
     // single upcast step, same validation/dedup as the old standalone
-    // r.eventMigration() call (folded into defineEvent, #1082 step 8).
+    // r.eventMigration() call (folded into defineEvent).
     function registerEventMigration(eventName, fromVersion, toVersion, transform) {
         if (toVersion !== fromVersion + 1) {
             throw new Error(`[Feature ${name}] defineEvent("${eventName}") migrations: only single-step migrations are allowed — toVersion must be fromVersion + 1 (got ${fromVersion} -> ${toVersion}). ` +
@@ -73,8 +73,8 @@ export function buildConfigEventsJobsMethods(state, name) {
             const [jobName, jobOptions, jobHandler] = typeof jobNameOrDefinition === "string"
                 ? [
                     jobNameOrDefinition,
-                    options,
-                    handler,
+                    requireArgument(options, name, "job", "options"),
+                    requireArgument(handler, name, "job", "handler"),
                 ]
                 : (() => {
                     const { name: definedJobName, handler: h, ...rest } = jobNameOrDefinition;
@@ -97,9 +97,9 @@ export function buildConfigEventsJobsMethods(state, name) {
                         'tz must be an IANA time zone name such as "Europe/Berlin".');
                 }
             }
-            // Resolve NameOrRef(s) in trigger.on. Multi-Trigger-Form: Array
-            // wird zu Array von resolved strings, Single bleibt single string —
-            // job-runner unterscheidet anhand Array.isArray.
+            // Resolve NameOrRef(s) in trigger.on. For the multi-trigger form, arrays
+            // become arrays of resolved strings while a single value remains a string;
+            // the job runner distinguishes them with Array.isArray.
             const trigger = "on" in jobOptions.trigger
                 ? {
                     on: Array.isArray(jobOptions.trigger.on)
@@ -114,7 +114,10 @@ export function buildConfigEventsJobsMethods(state, name) {
         },
         notification(notificationNameOrDefinition, definition) {
             const [notificationName, resolvedDefinition] = typeof notificationNameOrDefinition === "string"
-                ? [notificationNameOrDefinition, definition]
+                ? [
+                    notificationNameOrDefinition,
+                    requireArgument(definition, name, "notification", "definition"),
+                ]
                 : splitNamedDefinition(notificationNameOrDefinition);
             state.notifications[notificationName] = {
                 name: notificationName,
@@ -167,7 +170,7 @@ export function buildConfigEventsJobsMethods(state, name) {
         },
         metric(shortNameOrDefinition, options) {
             const [shortName, metricOptions] = typeof shortNameOrDefinition === "string"
-                ? [shortNameOrDefinition, options]
+                ? [shortNameOrDefinition, requireArgument(options, name, "metric", "options")]
                 : splitNamedDefinition(shortNameOrDefinition);
             if (state.metrics[shortName]) {
                 throw new Error(`[Feature ${name}] Metric "${shortName}" already registered. ` +
@@ -183,7 +186,7 @@ export function buildConfigEventsJobsMethods(state, name) {
         },
         secret(shortNameOrDefinition, options) {
             const [shortName, secretOptions] = typeof shortNameOrDefinition === "string"
-                ? [shortNameOrDefinition, options]
+                ? [shortNameOrDefinition, requireArgument(options, name, "secret", "options")]
                 : splitNamedDefinition(shortNameOrDefinition);
             if (state.secretKeys[shortName]) {
                 throw new Error(`[Feature ${name}] Secret "${shortName}" already registered. ` +
@@ -208,7 +211,7 @@ export function buildConfigEventsJobsMethods(state, name) {
         },
         secretNamespace(shortNameOrDefinition, options) {
             const [shortName, namespaceOptions] = typeof shortNameOrDefinition === "string"
-                ? [shortNameOrDefinition, options]
+                ? [shortNameOrDefinition, requireArgument(options, name, "secretNamespace", "options")]
                 : splitNamedDefinition(shortNameOrDefinition);
             if (state.secretNamespaces[shortName]) {
                 throw new Error(`[Feature ${name}] Secret namespace "${shortName}" already registered. ` +
@@ -227,7 +230,7 @@ export function buildConfigEventsJobsMethods(state, name) {
                 ? shortNameOrDefinition
                 : shortNameOrDefinition.name;
             const claimType = typeof shortNameOrDefinition === "string"
-                ? options.type
+                ? requireArgument(options, name, "claimKey", "options").type
                 : shortNameOrDefinition.type;
             if (state.claimKeys[shortName]) {
                 throw new Error(`[Feature ${name}] Claim key "${shortName}" already declared. ` +

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

@@ -3,7 +3,7 @@ import { toTableName } from "../db/table-builder.js";
 import { isEntityConventionQueryHandler, isPagedQueryHandler, PAGED_QUERY_HANDLER_BRAND, } from "./define-handler.js";
 import { assertEscapeHatchAccessIsSystemAdminOnly, registerCrudHandlers, } from "./entity-handlers.js";
 import { resolveName } from "./handler-helpers.js";
-import { isObjectArgument, throwObjectArgumentRequired } from "./object-form.js";
+import { isObjectArgument, requireArgument, throwObjectArgumentRequired } 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
@@ -42,9 +42,9 @@ function tryMapEntity(state, name, handlerName) {
             // skip: feature-name entity match is the preferred mapping
             return;
         }
-        const entityKeys = Object.keys(state.entities);
-        if (entityKeys.length === 1) {
-            state.handlerEntityMappings[handlerName] = entityKeys[0];
+        const [onlyEntityName, ...otherEntityNames] = Object.keys(state.entities);
+        if (onlyEntityName !== undefined && otherEntityNames.length === 0) {
+            state.handlerEntityMappings[handlerName] = onlyEntityName;
         }
     }
 }
@@ -97,7 +97,11 @@ export function buildEntityHandlerMethods(state, name) {
                     const { entity, name: innerName, ...rest } = entityRefOrDefinition;
                     return [entity, innerName, rest];
                 })()
-                : [entityRefOrDefinition, relationName, definition];
+                : [
+                    entityRefOrDefinition,
+                    requireArgument(relationName, name, "relation", "relation name"),
+                    requireArgument(definition, name, "relation", "definition"),
+                ];
             const entityName = resolveName(entityRef);
             if (!state.relations[entityName])
                 state.relations[entityName] = {};
@@ -126,6 +130,9 @@ export function buildEntityHandlerMethods(state, name) {
                 ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
                 ...(def.rateLimit && { rateLimit: def.rateLimit }),
                 ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
+                ...(def.rateLimitCost && {
+                    rateLimitCost: def.rateLimitCost, // @cast-boundary engine-bridge
+                }),
                 ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
                 ...transactionPhaseSlots(def),
                 ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),