@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

package/dist/engine/build-app-schema.js

@@ -111,7 +111,7 @@ export function buildAppSchema(registry, options = {}) {
         // instead so a leaked function renderer is actually caught.
         const offender = findNonJsonSafePath(schema, "schema");
         if (offender !== null) {
-            log.error(`buildAppSchema: Output ist nicht JSON-safe — nicht-serialisierbarer Wert bei "${offender}" (Funktions-Renderer oder Klassen-Instanz im Schema?).`, { offender });
+            log.error(`buildAppSchema: output is not JSON-safe, non-serializable value at "${offender}" (a function renderer or class instance in the schema?).`, { offender });
         }
     }
     return schema;
@@ -446,136 +446,96 @@ function assertValidScreenMultilineRows(featureName, shortId, screen) {
             check(screen.confirm.fields);
     }
 }
-// Per-field whitelist. Every forwarded value must be JSON-safe (literal, or
-// an array/plain-object built only from JSON-safe values) — even though the
-// FieldDefinition types only type `default` as a literal, the sample-authoring
-// pattern `as unknown as EntityDefinition` has already let function-valued
-// defaults slip through. This whitelist is defense-in-depth that catches them
-// BEFORE JSON.stringify silently drops them in the browser-injection pipeline.
-// The same check gates the structured properties below (`multiline`,
-// `derived`, `totals`, `totalsMatch`) — a top-level `Array.isArray`/plain-
-// object check alone would let a function survive one level deep.
-//
-// Cast at the exit `as EntityFieldDefinition`: type-system-wise our out-map only
-// satisfies the discriminated union with an unnarrowed `type` string — the
-// cast bridges the variant inference TS can't recompute from a generic
-// Record.
-// kumiko-lint-ignore complexity-budget flat per-property whitelist walk, one independent `if` per FieldDefinition property — same shape as schema-builder.ts's field→zod switch
-function projectField(fieldDef) {
-    const def = fieldDef; // @cast-boundary schema-walk
-    const out = {};
-    if (typeof def["type"] === "string")
-        out["type"] = def["type"];
-    if (typeof def["required"] === "boolean")
-        out["required"] = def["required"];
-    if (typeof def["sortable"] === "boolean")
-        out["sortable"] = def["sortable"];
+const isStringValue = (value) => typeof value === "string";
+const isBooleanValue = (value) => typeof value === "boolean";
+const isNumberValue = (value) => typeof value === "number";
+const isTrueValue = (value) => value === true;
+const isNumberOrStringValue = (value) => typeof value === "number" || typeof value === "string";
+const isBooleanOrJsonSafeObject = (value) => typeof value === "boolean" || isJsonSafeObject(value);
+const isUnitSpec = (value) => typeof value === "string" || (isPlainObject(value) && typeof value["field"] === "string");
+// Forwarded in this order, so the client schema keeps its key order.
+const FORWARDED_FIELD_PROPERTIES = [
+    ["type", isStringValue],
+    ["required", isBooleanValue],
+    ["sortable", isBooleanValue],
     // filterable controls the faceted filter dropdowns in the renderer (select/
     // boolean), so it must be included in the client schema.
-    if (typeof def["filterable"] === "boolean")
-        out["filterable"] = def["filterable"];
-    if (typeof def["searchable"] === "boolean")
-        out["searchable"] = def["searchable"];
-    if (isJsonSafeValue(def["default"]))
-        out["default"] = def["default"];
+    ["filterable", isBooleanValue],
+    ["searchable", isBooleanValue],
+    ["default", isJsonSafeValue],
     // Select: the options list is plain JSON, so forward it.
-    if (Array.isArray(def["options"]))
-        out["options"] = def["options"];
-    if (isJsonSafeObject(def["optionTones"]))
-        out["optionTones"] = def["optionTones"];
+    ["options", Array.isArray],
+    ["optionTones", isJsonSafeObject],
     // Reference: entity target, labelField, and multiple are required by the
     // renderer. ReferenceInput builds the options query from refEntity/refFeature
     // and resolves the label through labelField; without these properties, the
     // dropdown is empty (the QN becomes `<feature>:query::list` → 404).
-    if (typeof def["entity"] === "string")
-        out["entity"] = def["entity"];
-    if (typeof def["labelField"] === "string")
-        out["labelField"] = def["labelField"];
+    ["entity", isStringValue],
+    ["labelField", isStringValue],
     // Author-supplied picker source — without it the client falls back to the list handler.
-    if (typeof def["optionsQuery"] === "string")
-        out["optionsQuery"] = def["optionsQuery"];
+    ["optionsQuery", isStringValue],
     // Select: tier/tenant availability of the static options, loaded by the renderer.
-    if (typeof def["optionsAvailabilityQuery"] === "string")
-        out["optionsAvailabilityQuery"] = def["optionsAvailabilityQuery"];
+    ["optionsAvailabilityQuery", isStringValue],
     // Select: options only offered while a sibling-field condition holds; the renderer filters, the write path enforces.
-    if (Array.isArray(def["conditionalOptions"]))
-        out["conditionalOptions"] = def["conditionalOptions"];
-    if (typeof def["multiple"] === "boolean")
-        out["multiple"] = def["multiple"];
+    ["conditionalOptions", Array.isArray],
+    ["multiple", isBooleanValue],
     // MultiSelect: display picks checkboxes vs. combobox in the renderer,
     // columns/maxRows size the checkbox grid — without these the renderer
     // always falls back to the combobox. Select: display picks
     // "radio" | "dropdown" the same way.
-    if (typeof def["display"] === "string")
-        out["display"] = def["display"];
-    if (typeof def["columns"] === "number")
-        out["columns"] = def["columns"];
-    if (typeof def["maxRows"] === "number")
-        out["maxRows"] = def["maxRows"];
+    ["display", isStringValue],
+    ["columns", isNumberValue],
+    ["maxRows", isNumberValue],
     // text/longText: textarea row count — DefaultInput renders a single-line
     // input otherwise.
-    if (typeof def["multiline"] === "boolean" || isJsonSafeObject(def["multiline"]))
-        out["multiline"] = def["multiline"];
+    ["multiline", isBooleanOrJsonSafeObject],
     // number: Zod write-boundary bounds. date/timestamp/locatedTimestamp:
     // ISO-string picker bounds — same keys, different literal type.
-    if (typeof def["min"] === "number" || typeof def["min"] === "string")
-        out["min"] = def["min"];
-    if (typeof def["max"] === "number" || typeof def["max"] === "string")
-        out["max"] = def["max"];
+    ["min", isNumberOrStringValue],
+    ["max", isNumberOrStringValue],
     // date/timestamp/locatedTimestamp: display/parsing locale override.
-    if (typeof def["locale"] === "string")
-        out["locale"] = def["locale"];
+    ["locale", isStringValue],
     // image/images: which camera a mobile capture opens.
-    if (typeof def["capture"] === "string")
-        out["capture"] = def["capture"];
+    ["capture", isStringValue],
     // number: display-only suffix, static or read from a sibling field of the row.
-    const unit = def["unit"];
-    if (typeof unit === "string" || (isPlainObject(unit) && typeof unit["field"] === "string"))
-        out["unit"] = unit;
+    ["unit", isUnitSpec],
     // number/decimal/bigInt: `false` drops thousands separators (e.g. a year).
-    if (typeof def["grouping"] === "boolean")
-        out["grouping"] = def["grouping"];
+    ["grouping", isBooleanValue],
     // text: "password" masks the input and blocks URL prefill in the renderer.
-    if (typeof def["format"] === "string")
-        out["format"] = def["format"];
+    ["format", isStringValue],
     // Write-response redaction stays server-side; the renderer needs the flag to
     // refuse any prefill (URL or handoff) into the field.
-    if (def["sensitive"] === true)
-        out["sensitive"] = true;
+    ["sensitive", isTrueValue],
     // Without it the renderer shows a plain text input for a field whose value never leaves the server.
-    if (def["writeOnly"] === true)
-        out["writeOnly"] = true;
+    ["writeOnly", isTrueValue],
     // timestamp: the edit view-model derives its wall-clock input mode from this.
-    if (typeof def["locatedBy"] === "string")
-        out["locatedBy"] = def["locatedBy"];
+    ["locatedBy", isStringValue],
     // file/image/images: upload picker constraints; the first variant key picks
     // the preview variant.
-    if (isJsonSafeArray(def["accept"]))
-        out["accept"] = def["accept"];
-    if (typeof def["maxSize"] === "string")
-        out["maxSize"] = def["maxSize"];
-    if (isJsonSafeObject(def["variants"]))
-        out["variants"] = def["variants"];
+    ["accept", isJsonSafeArray],
+    ["maxSize", isStringValue],
+    ["variants", isJsonSafeObject],
     // decimal, incl. embedded sub-fields: rounding of derived embedded-list cells.
-    if (typeof def["scale"] === "number")
-        out["scale"] = def["scale"];
+    ["scale", isNumberValue],
     // money: declared currency source (MoneyCurrencySource) — without
     // it the renderer can't tell a "currency: { kind: 'tenant' }" field apart
     // from an undeclared one and always falls back to entity.defaultCurrency.
-    if (isJsonSafeObject(def["currency"]))
-        out["currency"] = def["currency"];
+    ["currency", isJsonSafeObject],
     // embedded lists: row-count bounds, computed cells, totals row, and the
     // sibling-money-field totals check.
-    if (typeof def["minItems"] === "number")
-        out["minItems"] = def["minItems"];
-    if (typeof def["maxItems"] === "number")
-        out["maxItems"] = def["maxItems"];
-    if (isJsonSafeObject(def["derived"]))
-        out["derived"] = def["derived"];
-    if (isJsonSafeArray(def["totals"]))
-        out["totals"] = def["totals"];
-    if (isJsonSafeObject(def["totalsMatch"]))
-        out["totalsMatch"] = def["totalsMatch"];
+    ["minItems", isNumberValue],
+    ["maxItems", isNumberValue],
+    ["derived", isJsonSafeObject],
+    ["totals", isJsonSafeArray],
+    ["totalsMatch", isJsonSafeObject],
+];
+function projectField(fieldDef) {
+    const def = fieldDef; // @cast-boundary schema-walk
+    const out = {};
+    for (const [key, isForwarded] of FORWARDED_FIELD_PROPERTIES) {
+        if (isForwarded(def[key]))
+            out[key] = def[key];
+    }
     // embedded lists: the sub-field map itself — without it the client-side
     // edit view-model iterates `undefined` and the screen crashes.
     // Recursive per sub-field, NOT a blanket isJsonSafeValue gate: a single

package/dist/engine/define-feature.js

@@ -48,9 +48,16 @@ export function defineFeature(name, setup, settings) {
         },
         requires: (() => {
             const fn = (...args) => {
-                if (!args.every(isObjectArgument))
+                const [first, ...rest] = args;
+                if (rest.length > 0 || !isObjectArgument(first)) {
                     throwObjectArgumentRequired(name, "requires");
-                state.requires.push(...resolveFeatureNamesArgs(args));
+                }
+                // Untyped callers can pass `{ feature: [...] }`; without this the object would be
+                // registered as a dependency name.
+                if (!Array.isArray(first.features) || !first.features.every((f) => typeof f === "string")) {
+                    throw new Error(`[Feature ${name}] r.requires() needs { features: string[] }`);
+                }
+                state.requires.push(...first.features);
             };
             return Object.assign(fn, {
                 projection: (tableName) => {

package/dist/engine/define-handler.js

@@ -57,6 +57,7 @@ export function defineWriteHandler(def,
         ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
         ...(def.rateLimit && { rateLimit: def.rateLimit }),
         ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
+        ...(def.rateLimitCost && { rateLimitCost: def.rateLimitCost }),
         ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
         ...pickPreTransactionPhases(def),
         ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),

package/dist/engine/entity-handlers.d.ts

@@ -44,6 +44,19 @@ export declare const entityListSchema: z.ZodObject<{
         }>;
         value: z.ZodUnknown;
     }, z.core.$strip>>>;
+    aggregate: z.ZodOptional<z.ZodObject<{
+        groupBy: z.ZodOptional<z.ZodString>;
+        measures: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            kind: z.ZodEnum<{
+                avg: "avg";
+                count: "count";
+                max: "max";
+                min: "min";
+                sum: "sum";
+            }>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare function defineEntityWriteHandler(name: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
 export declare function defineEntityQueryHandler(name: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;

package/dist/engine/entity-handlers.js

@@ -1,13 +1,16 @@
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
+import { listAggregatePayloadSchema, } from "@cosmicdrift/kumiko-types/list-aggregate-types";
 import * as z from "zod";
 import { collectReferenceFields, enrichRowWithReferences, enrichWithReferences, } from "../db/eagerload.js";
 import { createEventStoreExecutor } from "../db/event-store-executor.js";
+import { answerListAggregate } from "../db/list-aggregate-labels.js";
 import { buildEntityTable } from "../db/table-builder.js";
 import { acknowledgeConventionCrossTenant, reportConventionCrossTenantUse, } from "../db/tenant-db.js";
 import { InternalError } from "../errors/index.js";
 import { isSystemIdentity } from "../pipeline/system-identity-switch.js";
 import { assertUnreachable } from "../utils/index.js";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler.js";
+import { entityListRuntime } from "./entity-list-runtime-options.js";
 import { assertReason } from "./escape-hatch-reason.js";
 import { dropEmptyWriteOnlyValues } from "./field-access.js";
 import { instructionFieldNames } from "./instruction-fields.js";
@@ -105,6 +108,7 @@ export const entityListSchema = z.object({
         value: z.unknown(),
     }))
         .optional(),
+    aggregate: listAggregatePayloadSchema.optional(),
 });
 function parseHandlerName(name, validVerbs) {
     const colonIdx = name.indexOf(":");
@@ -390,28 +394,13 @@ export function defineEntityQueryHandler(name, entity, options) {
                 // runtime override supplies it.
                 const listPayload = query.payload; // @cast-boundary engine-payload
                 const db = dbFor(ctx);
-                const result = await executor.list(listPayload, query.user, db, {
-                    ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
-                    ...(ctx.includeDeleted === true && { includeDeleted: true }),
-                    // Registry access only exists at request time, so the
-                    // searchable-reference cache + entity resolver travel through the
-                    // same runtime-override extension point as searchAdapter above.
-                    referenceSearch: {
-                        fields: ctx.registry.getSearchableReferences(entityName),
-                        resolveEntity: (name) => ctx.registry.getEntity(name),
-                    },
-                    referenceSort: {
-                        fields: ctx.registry.getSortableReferences(entityName),
-                        resolveEntity: (name) => ctx.registry.getEntity(name),
-                    },
-                    parentVisibility: { entities: ctx.registry.getAllEntities() },
-                });
-                const eagerLoadViewer = {
-                    user: query.user,
-                    parentVisibility: { entities: ctx.registry.getAllEntities() },
-                };
+                const { runtimeOptions, eagerLoadViewer, resolveEntity } = entityListRuntime(ctx, entityName, query.user);
+                if (listPayload.aggregate !== undefined) {
+                    return answerListAggregate(executor, { ...listPayload, aggregate: listPayload.aggregate }, query.user, db, runtimeOptions, { entity, resolveEntity, viewer: eagerLoadViewer });
+                }
+                const result = await executor.list(listPayload, query.user, db, runtimeOptions);
                 const enrichedRows = hasRefFields
-                    ? await enrichWithReferences(result.rows, entity, (name) => ctx.registry.getEntity(name), db, eagerLoadViewer)
+                    ? await enrichWithReferences(result.rows, entity, resolveEntity, db, eagerLoadViewer)
                     : result.rows;
                 return { ...result, rows: augmentDerivedFields(enrichedRows, entity) };
             };

package/dist/engine/entity-list-runtime-options.d.ts

@@ -0,0 +1,8 @@
+import type { ListRuntimeOptions } from "@cosmicdrift/kumiko-types/event-store-executor-types";
+import type { EagerLoadEntityResolver, EagerLoadViewer } from "../db/eagerload.ts";
+import type { HandlerContext, SessionUser } from "./types/index.ts";
+export declare function entityListRuntime(ctx: HandlerContext, entityName: string, user: SessionUser): {
+    readonly runtimeOptions: ListRuntimeOptions;
+    readonly eagerLoadViewer: EagerLoadViewer;
+    readonly resolveEntity: EagerLoadEntityResolver;
+};

package/dist/engine/entity-list-runtime-options.js

@@ -0,0 +1,18 @@
+// Registry access only exists at request time, so the searchable/sortable-reference
+// caches, the entity resolver and the join-row read gate travel through the
+// runtime-override extension point of the executor verbs.
+export function entityListRuntime(ctx, entityName, user) {
+    const parentVisibility = { entities: ctx.registry.getAllEntities() };
+    const resolveEntity = (name) => ctx.registry.getEntity(name);
+    return {
+        runtimeOptions: {
+            ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
+            ...(ctx.includeDeleted === true && { includeDeleted: true }),
+            referenceSearch: { fields: ctx.registry.getSearchableReferences(entityName), resolveEntity },
+            referenceSort: { fields: ctx.registry.getSortableReferences(entityName), resolveEntity },
+            parentVisibility,
+        },
+        eagerLoadViewer: { user, parentVisibility },
+        resolveEntity,
+    };
+}

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

@@ -33,6 +33,7 @@ const WRITE_HANDLER_KEY_KINDS = {
     unsafeSkipTransitionGuard: "modeled",
     rateLimit: "modeled",
     additionalRateLimits: "modeled",
+    rateLimitCost: "opaque",
     escapeHatch: "modeled",
     tenantlessAnonymous: "opaque",
     reserveBeforeTransaction: "opaque",

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

@@ -2,19 +2,36 @@ import { SyntaxKind } from "ts-morph";
 import { describeUnknownFieldType, findUnknownEntityFieldTypes } from "../entity-field-types.js";
 import { sourceLocationFromNode } from "../source-location.js";
 import { fail, isPlainObject, isRawRefSentinel, ok, readDataLiteralNode, readNameLiteral, readNameOrRef, } from "./shared.js";
+function readBackingTableRef(property) {
+    const initializer = property.asKind(SyntaxKind.PropertyAssignment)?.getInitializer() ??
+        property.asKind(SyntaxKind.ShorthandPropertyAssignment)?.getNameNode();
+    const reference = initializer ? readDataLiteralNode(initializer) : undefined;
+    return isRawRefSentinel(reference) ? reference : undefined;
+}
 // `{ name: "x", ...xEntity }` — the definition is a reference the parser cannot
 // inline, so it is kept as a raw-ref sentinel and re-rendered as the same spread.
 // `backingTable` is runtime wiring (a table identifier), not part of the
-// definition data, so it does not take part in the shape check.
+// definition data, so it is carried next to the definition and skipped by the shape check.
 function readSpreadOnlyDefinition(obj) {
-    const properties = obj
-        .getProperties()
-        .filter((property) => property.asKind(SyntaxKind.PropertyAssignment)?.getName() !== "backingTable");
+    const isBackingTable = (property) => {
+        const name = property.asKind(SyntaxKind.PropertyAssignment)?.getName() ??
+            property.asKind(SyntaxKind.ShorthandPropertyAssignment)?.getName();
+        return name === "backingTable";
+    };
+    const allProperties = obj.getProperties();
+    const properties = allProperties.filter((property) => !isBackingTable(property));
     const spread = properties.length === 2 ? properties[1]?.asKind(SyntaxKind.SpreadAssignment) : undefined;
     if (!spread)
         return undefined;
     const reference = readDataLiteralNode(spread.getExpression());
-    return isRawRefSentinel(reference) ? reference : undefined;
+    if (!isRawRefSentinel(reference))
+        return undefined;
+    const backingTableProperty = allProperties.find(isBackingTable);
+    const backingTable = backingTableProperty ? readBackingTableRef(backingTableProperty) : undefined;
+    // A backingTable that is not a plain reference cannot be re-rendered; fall back to the data reader.
+    if (backingTableProperty && !backingTable)
+        return undefined;
+    return { definition: reference, backingTable };
 }
 export function extractEntity(call, sourceFile) {
     const args = call.getArguments();
@@ -32,7 +49,8 @@ export function extractEntity(call, sourceFile) {
         if (!nameInit) {
             return fail("entity", sourceLocationFromNode(call, sourceFile), "object form requires a string-literal `name` property");
         }
-        const definition = readSpreadOnlyDefinition(obj) ?? readDataLiteralNode(obj);
+        const spreadOnly = readSpreadOnlyDefinition(obj);
+        const definition = spreadOnly?.definition ?? readDataLiteralNode(obj);
         if (!isPlainObject(definition)) {
             return fail("entity", sourceLocationFromNode(call, sourceFile), "definition could not be read as a plain object (contains functions or identifiers)");
         }
@@ -49,6 +67,7 @@ export function extractEntity(call, sourceFile) {
             // Field-type membership is checked above; the cast is the extractor's
             // existing narrowing contract (readDataLiteralNode returns unknown).
             definition: defWithoutName,
+            ...(spreadOnly?.backingTable && { backingTable: spreadOnly.backingTable }),
         });
     }
     const entityName = readNameLiteral(first);

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

@@ -33,7 +33,8 @@
 // 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, readPropertyKey, resolveSameFileObjectLiteral, } from "./extractors/shared.js";
+import { readPropertyKey } from "./extractors/shared.js";
+import { callMatchesId } from "./pattern-id-matchers.js";
 import { indent, PATTERN_INDENT, renderPattern, renderValue } from "./render.js";
 /**
  * Apply a sequence of changes to the source file in-place. The list is
@@ -523,7 +524,7 @@ function findCallForId(sourceFile, id) {
             continue;
         if (propAccess.getName() !== id.kind)
             continue;
-        if (callMatchesId(call, id))
+        if (callMatchesId(call, id.kind, id))
             matches.push(call);
     }
     if (SINGLETON_KINDS.has(id.kind) && matches.length > 1) {
@@ -536,28 +537,6 @@ const AI_STEP_FACTORY = {
     "ai.extract": "aiExtractStep",
     "ai.classify": "aiClassifyStep",
 };
-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;
-}
 function findAiStepCall(sourceFile, id) {
     if (!isAiStepId(id))
         return undefined;
@@ -566,7 +545,7 @@ function findAiStepCall(sourceFile, id) {
     for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
         if (call.getExpression().getText() !== factory)
             continue;
-        if (callMatchesId(call, id))
+        if (callMatchesId(call, id.kind, id))
             matches.push(call);
     }
     if (matches.length > 1) {
@@ -574,163 +553,6 @@ function findAiStepCall(sourceFile, id) {
     }
     return matches[0];
 }
-function callMatchesId(call, id) {
-    switch (id.kind) {
-        // Singletons: kind alone identifies the call.
-        case "requires":
-        case "optionalRequires":
-        case "readsConfig":
-        case "systemScope":
-        case "toggleable":
-        case "describe":
-        case "uiHints":
-        case "config":
-        case "translations":
-        case "authClaims":
-        case "treeActions":
-            return true;
-        case "entity":
-            return (matchFirstArgString(call, id.entityName) || matchObjectProperty(call, "name", id.entityName));
-        case "relation":
-            // Positional: r.relation(entity, name, def) | Object: { entity, name, ... }
-            if (matchFirstArgString(call, id.entityName)) {
-                return matchArgString(call, 1, id.relationName);
-            }
-            return (matchObjectProperty(call, "entity", id.entityName) &&
-                matchObjectProperty(call, "name", id.relationName));
-        case "nav":
-        case "workspace":
-        case "screen":
-            return matchObjectProperty(call, "id", id.id);
-        case "writeHandler":
-        case "queryHandler":
-        case "streamHandler":
-            return (matchFirstArgString(call, id.handlerName) ||
-                matchObjectProperty(call, "name", id.handlerName));
-        case "hook":
-            // Positional: r.hook(type, target, fn) | Object: { type, target }
-            if (typeof id.target === "object") {
-                // 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.
-                if (matchFirstArgString(call, id.hookType)) {
-                    return matchAllOfArg(call.getArguments()[1], id.target.allOf);
-                }
-                return (matchObjectProperty(call, "type", id.hookType) &&
-                    matchObjectAllOfProperty(call, "target", 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));
-        case "metric":
-        case "secret":
-        case "secretNamespace":
-        case "claimKey":
-            return (matchFirstArgString(call, id.shortName) || matchObjectProperty(call, "name", id.shortName));
-        case "referenceData":
-            return (matchFirstArgString(call, id.entityName) ||
-                matchObjectProperty(call, "entity", id.entityName));
-        case "useExtension":
-            // Positional: r.useExtension(name, entity) | Object: { name, entity }
-            if (matchFirstArgString(call, id.extensionName)) {
-                return matchArgNameOrRef(call, 1, id.entityName);
-            }
-            return (matchObjectProperty(call, "name", id.extensionName) &&
-                matchObjectProperty(call, "entity", id.entityName));
-        case "job":
-            return matchFirstArgString(call, id.jobName) || matchObjectProperty(call, "name", id.jobName);
-        case "notification":
-            return (matchFirstArgString(call, id.notificationName) ||
-                matchObjectProperty(call, "name", id.notificationName));
-        case "httpRoute":
-            // Object form only; positional doesn't apply.
-            return (matchObjectProperty(call, "method", id.method) && matchObjectProperty(call, "path", id.path));
-        case "projection":
-        case "multiStreamProjection":
-            return matchObjectProperty(call, "name", id.name);
-        case "defineEvent":
-            return (matchFirstArgString(call, id.eventName) || matchObjectProperty(call, "name", id.eventName));
-        case "extendsRegistrar":
-            return matchFirstArgString(call, id.extensionName);
-        case "ai.generate":
-        case "ai.extract":
-        case "ai.classify":
-            return readAiStepKey(call) === id.stepKey;
-        default: {
-            const _exhaustive = id;
-            return _exhaustive;
-        }
-    }
-}
-// 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);
-}
 // =============================================================================
 // Format helpers — line boundaries / blank-line collapse
 // (indent / PATTERN_INDENT live in render.ts and are imported above.)