@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/engine/factories.js

@@ -24,7 +24,7 @@ function resolvePersonalFlags(personal, reason) {
         userOwned: { ownerField: personal.of, ...(whenAbsent !== undefined && { whenAbsent }) },
     };
 }
-// Resolves the author-facing `personal`/`find` annotations (kumiko-framework#2250)
+// Resolves the author-facing `personal`/`find` annotations
 // into the internal ResolvedPiiFlags every factory below merges into its
 // return value. `personal`, `find`, `reason` never survive into the field def.
 function expandPersonalAnnotations(overrides) {
@@ -73,7 +73,7 @@ function missingTextFieldStanceError(factoryName) {
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
-// Fail-closed stance gate (kumiko-framework#2921) for the two text-shaped
+// Fail-closed stance gate for the two text-shaped
 // factories — runs before expandPersonalAnnotations so an untyped JS caller
 // (no compiler to stop it) can't slip an unannotated text field past the
 // type layer either. The typed signature above already rejects a
@@ -109,13 +109,12 @@ function assertTextFieldStance(factoryName, overrides) {
         throw missingTextFieldStanceError(factoryName);
     }
 }
-// Generic über `R extends true | false` (statt `boolean`) damit
-// `createTextField({ required: true })` literal `required: true` im
-// Return-Type behält. `boolean` würde widenen — EntityTable<E>'s
-// Mapped-Type könnte dann nicht zwischen `required: true` und
-// `required: false` dispatchen, jede Column würde zu nullable
-// degradieren. Default `R = false` matcht den runtime-default. Pattern
-// in jeder required-bearing factory unten.
+// Use generic `R extends true | false` instead of `boolean` so
+// `createTextField({ required: true })` preserves the literal `required: true`
+// in the return type. Widening to `boolean` would prevent EntityTable<E>'s
+// Mapped-Type from distinguishing `required: true` from `required: false`,
+// making every column nullable. Default `R = false` matches the runtime
+// default. This pattern is used in every required-bearing factory below.
 export function createTextField(overrides) {
     assertTextFieldStance("createTextField", overrides);
     return {
@@ -129,13 +128,13 @@ export function createTextField(overrides) {
 }
 /**
  * Long-form text field for source-code, markdown, blog-posts, email-
- * templates — anything that can be megabytes large. Type-level differs
- * from `text`: keine sortable/searchable/filterable/format options.
- * DB-mapping ist identisch zu text (PG text ist unbounded).
+ * templates — anything that can be megabytes large. Its type-level API
+ * differs from `text`: it has no sortable/searchable/filterable/format options.
+ * The DB mapping is identical to text (`PG text` is unbounded).
  *
- * Soft-cap default: kein maxLength (PG text ist 1 GB hart begrenzt).
- * Setze einen explicit `maxLength` wenn du ein verirrtes Browser-Paste
- * früh ablehnen willst (z.B. 1_000_000 = 1 MB).
+ * Soft-cap default: no maxLength (`PG text` has a 1 GB hard limit).
+ * Set an explicit `maxLength` to reject an accidental browser paste early
+ * (for example, `1_000_000 = 1 MB`).
  */
 /**
  * Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`).
@@ -277,10 +276,10 @@ export function createEmbeddedListField(schema, overrides) {
         multiple: true,
     };
 }
-// Free-form jsonb-Spalte — siehe `JsonbFieldDef`-Doku. Schema-less, default
-// `{}`, NOT NULL. Hauptnutzer: custom-fields-Bundle (host-entity's
-// `customFields`-Spalte). Andere valid uses: tenant-config-blobs, AI-
-// inferred-metadata, future tags-arrays.
+// Free-form jsonb column — see the `JsonbFieldDef` documentation. Schema-less,
+// defaults to `{}`, and is NOT NULL. Primarily used by the custom-fields
+// bundle for the host entity's `customFields` column; other valid uses include
+// tenant configuration blobs, AI-inferred metadata, and future tag arrays.
 export function createJsonbField(overrides) {
     return {
         type: "jsonb",
@@ -295,17 +294,17 @@ export function createDateField(overrides) {
     }; // @cast-boundary engine-payload
 }
 /**
- * UTC-Instant — für Ereignisse die zu einem bestimmten Zeitpunkt passieren
- * (createdAt, loginAt, actualPickupAt). Temporal.Instant intern.
+ * UTC instant for events occurring at a specific point in time
+ * (createdAt, loginAt, actualPickupAt). Uses Temporal.Instant internally.
  *
- * Mit `locatedBy: "<name>Tz"` wird das Feld zum Wall-Clock-Pair eines
- * Termins an einem Ort — bevorzuge dafür `createLocatedTimestampField()`,
- * das EIN atomares Feld statt eines lose verdrahteten Pairs erzeugt.
+ * With `locatedBy: "<name>Tz"`, the field becomes a wall-clock pair for an
+ * appointment at a location — prefer `createLocatedTimestampField()` instead,
+ * which creates one atomic field rather than a loosely connected pair.
  */
 export function createTimestampField(overrides) {
-    // Object-Build vermeidet hartcodiertes `required: false` im literal —
-    // das würde TS dazu bringen, R auf `boolean` zu widenen statt das
-    // literal `true`/`false` aus dem overrides-Argument zu inferieren.
+    // Building the object this way avoids hardcoding `required: false` in the
+    // literal, which would make TypeScript widen R to `boolean` instead of
+    // inferring the `true`/`false` literal from the overrides argument.
     return {
         ...expandPersonalAnnotations(overrides),
         type: "timestamp",
@@ -313,8 +312,9 @@ export function createTimestampField(overrides) {
     };
 }
 /**
- * IANA-Zonenname (z.B. "Europe/Berlin"). Wird im Boot/Schema-Validator
- * via `Intl.supportedValuesOf("timeZone")` geprüft (kommt im Zod-Schritt).
+ * IANA time-zone name (for example, "Europe/Berlin"). The boot/schema
+ * validator checks it using `Intl.supportedValuesOf("timeZone")` during the
+ * Zod step.
  */
 export function createTzField(overrides) {
     return {
@@ -372,14 +372,15 @@ export function createFilesField(overrides) {
 export function createImagesField(overrides) {
     return { type: "images", ...expandPersonalAnnotations(overrides) };
 }
-// `F` läuft OHNE Constraint im Generic-Param damit TS die literal-types
-// einzelner Field-Defs durchzieht (required: true bleibt true, nicht
-// boolean). Constraint-Match gegen FieldsMap würde widenen — siehe TS-
-// Issue um Constraint-Inferenz auf strukturellen Records. Stattdessen
-// validieren wir die Conformance via conditional return type: wenn F
-// nicht FieldsMap-compat ist, kollabiert der Return zu `never`.
-// `const F`: inline field literals (`{ type: "reference", ... }`) keep their
-// `type` literal without `as const`; otherwise it widens to string → `never`.
+// Leave `F` unconstrained so TypeScript preserves the literal types of
+// individual field definitions (`required: true` remains `true`, not
+// `boolean`). Constraining it to FieldsMap would widen them — see the
+// TypeScript issue concerning constraint inference for structural records.
+// Instead, conformance is validated through the conditional return type: if F
+// is not compatible with FieldsMap, the return type collapses to `never`.
+// `const F` preserves the `type` literal in inline field literals
+// (`{ type: "reference", ... }`) without `as const`; otherwise it widens to
+// string and produces `never`.
 export function createEntity(def) {
     return {
         softDelete: false,

package/dist/engine/feature-ast/entity-field-types.js

@@ -1,7 +1,7 @@
 // Shared field-type validation for EntityDefinition. Used by both the
 // static extractor (extractEntity, parse-time ParseError) and the runtime
 // PatternChange validator (pattern-change-schema.ts) so the two never drift
-// into reporting different "unknown field type" catalogues (#3137).
+// into reporting different "unknown field type" catalogues.
 import { FIELD_TYPE_NAMES } from "@cosmicdrift/kumiko-types/fields";
 import { isPlainObject, isRawRefSentinel } from "./extractors/shared.js";
 /**

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",
@@ -256,7 +257,7 @@ export function parseHandlerCall(call, sourceFile, methodName) {
     // (`r.writeHandler(eventCreateHandler)`, `r.queryHandler(someQuery())`)
     // that resolveObjectLiteralArg above couldn't turn into an object literal
     // (imported binding, factory call, ...). Keep it recognised as this kind
-    // instead of ParseErroring — see #1007. Opaque: renderWriteHandler/
+    // instead of ParseErroring. Opaque: renderWriteHandler/
     // renderQueryHandler re-emit `source.raw` verbatim when handlerName is
     // undefined.
     if (args.length === 1 && isRawRefSentinel(readDataLiteralNode(first))) {

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

@@ -230,7 +230,7 @@ export function extractHook(call, sourceFile) {
         ...escapeHatchOutcome,
     });
 }
-// guard:dup-ok — intentionale Parallele zu extractTree (round6); verschiedene Feature-AST-Extraktoren by design
+// guard:dup-ok — intentional parallel to extractTree; different Feature-AST extractors by design
 export function extractAuthClaims(call, sourceFile) {
     const arg = call.getArguments()[0];
     if (!arg) {

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/extractors/shared.d.ts

@@ -47,8 +47,7 @@ export declare function readStringOrRaw(node: Node): string | RawRefSentinel | u
  * Like readStringLiteralArgs, but an argument that resolves to a raw-ref
  * sentinel is kept as that sentinel instead of failing the whole call. Used
  * where a value stands in for a single name/key and inlining its resolved
- * string would corrupt the render roundtrip (e.g. `r.requires(someFeature.name)`
- * — see #1009).
+ * string would corrupt the render roundtrip (e.g. `r.requires(someFeature.name)`).
  */
 export declare function readStringOrRawArgs(call: CallExpression): readonly (string | RawRefSentinel)[] | undefined;
 export { isPlainObject } from "../../../utils/is-plain-object.ts";
@@ -67,7 +66,7 @@ export type NameLiteralRef = {
 };
 /**
  * Like `readNameLiteral`, but for callers that must preserve an
- * identifier-authored name across a render → parse round-trip (see #2111).
+ * identifier-authored name across a render → parse round-trip.
  * `raw` is populated only when the node resolved via an identifier — a
  * string-literal node has nothing worth preserving beyond its value, and
  * setting `raw` for it too would make `JSON.stringify(value)` and

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

@@ -147,8 +147,7 @@ export function readStringOrRaw(node) {
  * Like readStringLiteralArgs, but an argument that resolves to a raw-ref
  * sentinel is kept as that sentinel instead of failing the whole call. Used
  * where a value stands in for a single name/key and inlining its resolved
- * string would corrupt the render roundtrip (e.g. `r.requires(someFeature.name)`
- * — see #1009).
+ * string would corrupt the render roundtrip (e.g. `r.requires(someFeature.name)`).
  */
 export function readStringOrRawArgs(call) {
     const out = [];
@@ -229,7 +228,7 @@ function resolveIdentifierToStringLiteral(identifier) {
 }
 /**
  * Like `readNameLiteral`, but for callers that must preserve an
- * identifier-authored name across a render → parse round-trip (see #2111).
+ * identifier-authored name across a render → parse round-trip.
  * `raw` is populated only when the node resolved via an identifier — a
  * string-literal node has nothing worth preserving beyond its value, and
  * setting `raw` for it too would make `JSON.stringify(value)` and

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

@@ -17,8 +17,8 @@
 //   - Top-level code outside `defineFeature(...)`. Designer/AI treat
 //     such files as "not a feature file".
 //
-// **Skeleton status (C1.3):** interface fixed, extractors are TODO.
-// Per-pattern extractors fill in iteratively (C1.5) — each round adds
+// **Skeleton status:** interface fixed, extractors are TODO.
+// Per-pattern extractors fill in iteratively — each iteration 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, extractSecretNamespace, extractStoreTable, extractStreamHandler, extractSystemScope, extractToggleable, extractTranslations, extractTreeActions, extractUiHints, extractUseExtension, extractUsesApi, extractWorkspace, extractWriteHandler, findFunctionLiteral, findImportBindingForLocalName, readObjectPropertyInitializer, resolveModuleFile, resolveSameFileObjectLiteral, } from "./extractors/index.js";
@@ -185,7 +185,7 @@ function walkSetupCallback(body, registrarParamName, sourceFile, patterns, error
         // a registrar-wrapper call — a function that receives the registrar as
         // a bare argument, e.g. `registerShowPonyScreens(r)`. Such wrappers are
         // invisible to a receiver-shape match, so we resolve the callee (same
-        // file, or the declaring file of a named import — #1008) and recurse
+        // file, or the declaring file of a named import) and recurse
         // into its body with its own parameter name for the registrar slot.
         const wrapper = resolveRegistrarWrapperCall(call, registrarParamName);
         if (!wrapper)
@@ -368,7 +368,7 @@ function walkAiStepCalls(body, registrarParamName, sourceFile, patterns, errors,
     }
 }
 // =============================================================================
-// Internal — pattern extractors (skeleton, implementation in C1.5)
+// Internal — pattern extractors
 // =============================================================================
 /**
  * Route an `<r>.<method>(...)` call to its concrete extractor. New
@@ -377,12 +377,12 @@ function walkAiStepCalls(body, registrarParamName, sourceFile, patterns, errors,
  * commit to the new kind via compile errors.
  *
  * Skeleton: every recognised method currently returns an UnknownPattern
- * with the right method name. C1.5 replaces the cases with concrete
- * extractors one at a time.
+ * with the right method name. Extractors replace the cases with concrete
+ * implementations one at a time.
  */
 function dispatchExtractor(methodName, call, sourceFile) {
     switch (methodName) {
-        // Round 1 — simplest static patterns
+        // Simplest static patterns
         case "requires":
             return extractRequires(call, sourceFile);
         case "optionalRequires":
@@ -397,7 +397,7 @@ function dispatchExtractor(methodName, call, sourceFile) {
             return extractDescribe(call, sourceFile);
         case "uiHints":
             return extractUiHints(call, sourceFile);
-        // Round 2 — object-literal-based static patterns
+        // Object-literal-based static patterns
         case "entity":
             return extractEntity(call, sourceFile);
         case "relation":
@@ -406,7 +406,7 @@ function dispatchExtractor(methodName, call, sourceFile) {
             return extractNav(call, sourceFile);
         case "workspace":
             return extractWorkspace(call, sourceFile);
-        // Round 3 — complex static patterns
+        // Complex static patterns
         case "config":
             return extractConfig(call, sourceFile);
         case "translations":
@@ -423,7 +423,7 @@ function dispatchExtractor(methodName, call, sourceFile) {
             return extractReferenceData(call, sourceFile);
         case "useExtension":
             return extractUseExtension(call, sourceFile);
-        // Round 4 — mixed (header + body) patterns
+        // Mixed (header + body) patterns
         case "hook":
             return extractHook(call, sourceFile);
         case "authClaims":
@@ -448,7 +448,7 @@ function dispatchExtractor(methodName, call, sourceFile) {
             return extractMultiStreamProjection(call, sourceFile);
         case "screen":
             return extractScreen(call, sourceFile);
-        // Round 5 — opaque patterns
+        // Opaque patterns
         case "extendsRegistrar":
             return extractExtendsRegistrar(call, sourceFile);
         case "usesApi":
@@ -459,10 +459,10 @@ function dispatchExtractor(methodName, call, sourceFile) {
             return extractStoreTable(call, sourceFile);
         case "bootCheck":
             return extractBootCheck(call, sourceFile);
-        // Round 6 — Tree-Actions pattern
+        // Tree-Actions pattern
         case "treeActions":
             return extractTreeActions(call, sourceFile);
-        // Round 7 — env-schema contract (opaque, Zod-expression argument)
+        // Env-schema contract (opaque, Zod-expression argument)
         case "envSchema":
             return extractEnvSchema(call, sourceFile);
         // Unknown method — UnknownPattern signal so Designer/AI surface it

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, ...)`, see #1746).
-//
-// 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.)

package/dist/engine/feature-ast/pattern-change-schema.d.ts

@@ -7,6 +7,7 @@ import type { RelationDefinition } from "../types/relations.ts";
 import type { ScreenDefinition } from "../types/screen.ts";
 import type { TreeActionDef } from "../types/tree-node.ts";
 import type { WorkspaceDefinition } from "../types/workspace.ts";
+import type { RawRefSentinel } from "./extractors/shared.ts";
 import type { PatternChange } from "./patch.ts";
 import type { SourceLocation } from "./source-location.ts";
 export type PatternChangeIssue = {
@@ -26,6 +27,7 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
         source: z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>;
         entityName: z.ZodString;
         definition: z.ZodType<EntityDefinition, unknown, z.core.$ZodTypeInternals<EntityDefinition, unknown>>;
+        backingTable: z.ZodOptional<z.ZodType<RawRefSentinel, unknown, z.core.$ZodTypeInternals<RawRefSentinel, unknown>>>;
     }, z.core.$strict>;
     relation: z.ZodObject<{
         kind: z.ZodLiteral<"relation">;
@@ -648,6 +650,7 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     source: z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>;
     entityName: z.ZodString;
     definition: z.ZodType<EntityDefinition, unknown, z.core.$ZodTypeInternals<EntityDefinition, unknown>>;
+    backingTable: z.ZodOptional<z.ZodType<RawRefSentinel, unknown, z.core.$ZodTypeInternals<RawRefSentinel, unknown>>>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"relation">;
     source: z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>;

package/dist/engine/feature-ast/pattern-change-schema.js

@@ -2,7 +2,7 @@
 // tool (or any external caller) hands us JSON; before it ever reaches
 // `applyChanges` it must pass through here. Every rejection carries an
 // exact dotted/bracketed path so the caller (frequently an LLM) can
-// self-correct without a human in the loop — see kumiko-framework#3137.
+// self-correct without a human in the loop.
 //
 // **Zod v4 constraint driving this file's shape:** every discriminated-
 // union member below stays a plain `z.object(...)` (or `.superRefine`
@@ -332,6 +332,7 @@ const entitySchema = z
     source: sourceFieldSchema,
     entityName: z.string(),
     definition: entityDefinitionSchema,
+    backingTable: passthroughSchema().optional(),
 })
     .strict();
 const relationSchema = z

package/dist/engine/feature-ast/pattern-id-matchers.d.ts

@@ -0,0 +1,7 @@
+import { type CallExpression } from "ts-morph";
+import type { PatternId } from "./patch.ts";
+import type { MembersByKind } from "./patterns.ts";
+type PatternIdKind = PatternId["kind"];
+type PatternIdOfKind = MembersByKind<PatternId>;
+export declare function callMatchesId<K extends PatternIdKind>(call: CallExpression, kind: K, id: PatternIdOfKind[K]): boolean;
+export {};