@cosmicdrift/kumiko-framework 0.220.1 → 0.222.0

package/src/engine/boot-validator/__tests__/i18n-keys.test.ts

@@ -1,8 +1,28 @@
 import { describe, expect, test } from "bun:test";
+import { buildConfigFeatureSchema } from "../../build-config-feature-schema";
 import { access, createTenantConfig } from "../../config-helpers";
 import { defineFeature } from "../../define-feature";
+import { createRegistry } from "../../registry";
+import { isFieldsEditSection } from "../../screen-helpers";
+import type { ConfigEditScreenDefinition } from "../../types";
 import { validateBoot } from "../index";
 
+// Mirrors packages/bundled-features/src/config/i18n.ts — the audience-parent
+// labels every masked config key's generated hub requires regardless of
+// which feature owns the key or which scope its keys are visible at
+// (requiredKeysFromGeneratedConfigHub adds all four unconditionally once
+// any masked key exists, see i18n-keys.ts:35-38).
+const configHub = defineFeature("config", (r) => {
+  r.translations({
+    keys: {
+      "config.settings.title": { en: "Settings" },
+      "config.settings.system": { en: "Platform" },
+      "config.settings.tenant": { en: "Tenant" },
+      "config.settings.user": { en: "Personal" },
+    },
+  });
+});
+
 // fw#2260: the Settings-Hub generator (buildConfigFeatureSchema) labels a
 // masked config key's generated nav entry / configEdit section with the
 // dot-form key `${feature}.settings` — never colon-form. isI18nKey's
@@ -10,20 +30,6 @@ import { validateBoot } from "../index";
 // feature could ship a generated Settings screen whose label was never
 // translated and boot validation stayed silent.
 describe("validateI18nSurfaceKeys — Settings-Hub generated dot-form label (fw#2260)", () => {
-  // Mirrors packages/bundled-features/src/config/i18n.ts — the audience-parent
-  // labels every masked config key's generated hub requires regardless of
-  // which feature owns the key.
-  const configHub = defineFeature("config", (r) => {
-    r.translations({
-      keys: {
-        "config.settings.title": { en: "Settings" },
-        "config.settings.system": { en: "Platform" },
-        "config.settings.tenant": { en: "Organization" },
-        "config.settings.user": { en: "Personal" },
-      },
-    });
-  });
-
   function billingFeature(translationKeys: Record<string, { readonly en: string }>) {
     return defineFeature("billing", (r) => {
       r.config({
@@ -61,4 +67,131 @@ describe("validateI18nSurfaceKeys — Settings-Hub generated dot-form label (fw#
     });
     expect(() => validateBoot([configHub, billing])).not.toThrow();
   });
+
+  test("group namespace ≠ feature name: blank translation key satisfies hub label", () => {
+    const billing = defineFeature("billing", (r) => {
+      r.config({
+        keys: {
+          apiKey: createTenantConfig("text", {
+            write: access.roles("TenantAdmin"),
+            group: "tenant-settings",
+            mask: { title: "billing.api-key" },
+          }),
+        },
+      });
+      r.translations({
+        keys: {
+          "billing.api-key": { en: "API Key" },
+          "screen:tenant-settings-tenant.title": { en: "Tenant Settings" },
+          "tenant-settings.settings": { en: "Tenant Settings" },
+        },
+      });
+    });
+    expect(() => validateBoot([configHub, billing])).not.toThrow();
+  });
+});
+
+// PR #2314 idx2: buildConfigFeatureSchema varies the generated dot-form label
+// along two more paths that fw#2260's tests above never exercise — a tenant
+// key with an elevated (SystemAdmin) write role surfaces the same feature
+// under a second, broader scope (build-config-feature-schema.ts:142-158), and
+// a feature can opt into a configEdit section description
+// (build-config-feature-schema.ts:246-249). The `group`-namespace path is
+// deliberately left untested here — fw#2314 idx1 tracks it as broken
+// (treatDotFormAsKey requires an unsatisfiable `${group}.settings` key for a
+// namespace that has no matching feature), and a test would either fail on
+// the open bug or paper over it; it belongs with the idx1 fix, not this batch.
+describe("validateI18nSurfaceKeys — scoped label fallback for elevated write roles (PR #2314 idx2)", () => {
+  function opsFeature(translationKeys: Record<string, { readonly en: string }>) {
+    return defineFeature("ops", (r) => {
+      r.config({
+        keys: {
+          // Home scope tenant + an elevated SystemAdmin write role surfaces
+          // "ops" under BOTH the tenant audience (home, full write set) and
+          // the system audience (cascade, write set ∩ ELEVATED_ROLES.system)
+          // — two navs/screens for one feature.
+          maintenanceMode: createTenantConfig("boolean", {
+            write: access.roles("TenantAdmin", "SystemAdmin"),
+            mask: { title: "ops.maintenance-mode" },
+          }),
+        },
+      });
+      if (Object.keys(translationKeys).length > 0) {
+        r.translations({ keys: translationKeys });
+      }
+    });
+  }
+
+  test("elevated write role surfaces the feature at two scopes; the scoped override labels the system nav while the tenant nav falls back to the plain key", () => {
+    const translations = {
+      "ops.maintenance-mode": { en: "Maintenance Mode" },
+      "screen:ops-tenant.title": { en: "Ops Settings" },
+      "screen:ops-system.title": { en: "Ops Settings (Platform)" },
+      // Required unconditionally: both screens' section title is always
+      // `${feature}.settings` (build-config-feature-schema.ts:248).
+      "ops.settings": { en: "Ops" },
+      // Opt-in scoped override — only the system (cascade) nav uses it.
+      "ops.settings.system": { en: "Ops (Platform Cascade)" },
+    };
+    const ops = opsFeature(translations);
+
+    const schema = buildConfigFeatureSchema(createRegistry([configHub, ops]));
+    expect(schema.navs.find((n) => n.id === "ops-system")?.label).toBe("ops.settings.system");
+    expect(schema.navs.find((n) => n.id === "ops-tenant")?.label).toBe("ops.settings");
+
+    expect(() => validateBoot([configHub, ops])).not.toThrow();
+  });
+});
+
+// isI18nKeys.ts's requiredKeysFromScreen never reads EditFieldsSection.description
+// (only title + field labels, see required-surface-keys.ts:210-224), so this
+// gate is invisible to validateBoot either way — a validateBoot(...).not.toThrow()
+// assertion alone would pass identically with build-config-feature-schema.ts:249
+// deleted outright. Assert on the generated schema itself instead, the only
+// artifact the gate actually changes.
+describe("validateI18nSurfaceKeys — gated configEdit section description (PR #2314 idx2)", () => {
+  function reportingFeature(translationKeys: Record<string, { readonly en: string }>) {
+    return defineFeature("reporting", (r) => {
+      r.config({
+        keys: {
+          retentionDays: createTenantConfig("number", {
+            write: access.roles("TenantAdmin"),
+            mask: { title: "reporting.retention-days" },
+          }),
+        },
+      });
+      r.translations({ keys: translationKeys });
+    });
+  }
+
+  function reportingSection(translationKeys: Record<string, { readonly en: string }>) {
+    const reporting = reportingFeature(translationKeys);
+    const schema = buildConfigFeatureSchema(createRegistry([configHub, reporting]));
+    const screen = schema.screens.find(
+      (s): s is ConfigEditScreenDefinition => s.type === "configEdit",
+    );
+    if (screen === undefined) throw new Error("expected a generated configEdit screen");
+    const section = screen.layout.sections[0];
+    if (section === undefined || !isFieldsEditSection(section)) {
+      throw new Error("expected a fields section");
+    }
+    return section;
+  }
+
+  test("declaring 'reporting.settings.description' adds it to the generated section; omitting it leaves the section without one", () => {
+    const withDescription = reportingSection({
+      "reporting.retention-days": { en: "Retention (days)" },
+      "screen:reporting-tenant.title": { en: "Reporting Settings" },
+      "reporting.settings": { en: "Reporting" },
+      "reporting.settings.description": { en: "Configure how long reports are kept." },
+    });
+    expect(withDescription.description).toBe("reporting.settings.description");
+
+    const withoutDescription = reportingSection({
+      "reporting.retention-days": { en: "Retention (days)" },
+      "screen:reporting-tenant.title": { en: "Reporting Settings" },
+      "reporting.settings": { en: "Reporting" },
+    });
+    expect(withoutDescription.description).toBeUndefined();
+  });
 });

package/src/engine/boot-validator/entity-handler.ts

@@ -587,6 +587,11 @@ function validateEmbeddedDerivedCells(
           `Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" reading unknown sub-field "${sourceName}".`,
         );
       }
+      if (sourceName in field.derived) {
+        throw new Error(
+          `Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" reading derived sub-field "${sourceName}".`,
+        );
+      }
     }
   }
 }

package/src/engine/boot-validator/pii-retention.ts

@@ -218,20 +218,32 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
       }
 
       if (retention.strategy === "blockDelete") {
-        // blockDelete on an entity with no subject field is the correct
-        // "never auto-delete" choice; User-Forget never reaches those rows (#1622).
-        const hasSubjectField = Object.values(fieldsByName).some(
+        // blockDelete with no field that can carry `anonymize` is fine;
+        // subjectRef-only entities are covered by the V3 EXT_USER_DATA guard
+        // instead (#1622, #2336).
+        const entityHasAnonymizableSubjectField = Object.values(fieldsByName).some(
           (f) => hasAnonymizableSubjectField(f as ResolvedPiiFlags), // @cast-boundary schema-walk
         );
         const hasAnonymize = Object.values(fieldsByName).some((f) => {
           const a = f as ResolvedPiiFlags; // @cast-boundary schema-walk
           return Boolean(a.anonymize);
         });
-        if (hasSubjectField && !hasAnonymize) {
+        if (entityHasAnonymizableSubjectField && !hasAnonymize) {
           // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
           console.warn(
             `[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.strategy="blockDelete" but no field has an anonymize-function. User-Forget cannot anonymize — Forget will return error. Add { anonymize: () => null } or () => "[ANONYMIZED]" to PII fields.`,
           );
+        } else if (!entityHasAnonymizableSubjectField) {
+          const hasSubjectRef = Object.values(fieldsByName).some((f) => {
+            const a = f as ResolvedPiiFlags; // @cast-boundary schema-walk
+            return Boolean(a.subjectRef);
+          });
+          if (hasSubjectRef) {
+            // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+            console.warn(
+              `[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.strategy="blockDelete" with subjectRef-only PII relies on the EXT_USER_DATA delete hook for Art.17 — make sure it is not a no-op.`,
+            );
+          }
         }
       }
     }

package/src/engine/boot-validator/screens.ts

@@ -20,7 +20,7 @@ import type {
   EditLayout,
   FieldCondition,
   RowAction,
-  RowActionNavigate,
+  RowActionNavigateBase,
   RowFieldExtractor,
   ScreenDefinition,
   ToolbarAction,
@@ -345,12 +345,19 @@ function validateToolbarDrawerAction(
 // call sites so the mutual-exclusivity check and the entity→detailFor
 // resolution don't drift between them (same drift risk
 // validateRowActionNavigateParams above is already shared to avoid).
+// Runtime-loose shape: boot still rejects both/neither for untyped schemas;
+// authors get the exclusive union via RowActionNavigate (#2303).
+type RowActionNavigateRuntime = RowActionNavigateBase & {
+  readonly screen?: string;
+  readonly entity?: string;
+};
+
 function resolveRowActionNavigateTarget(
   featureName: string,
   screenId: string,
   screenType: "entityList" | "projectionList" | "projectionDetail",
   actionLabel: "rowAction" | "action",
-  action: RowActionNavigate,
+  action: RowActionNavigateRuntime,
   allScreenQns: ReadonlySet<string>,
   navTargetShortIds: ReadonlySet<string>,
   screensByShortId: ReadonlyMap<

package/src/engine/embedded-derived.ts

@@ -1,13 +1,11 @@
 import type { EmbeddedDerivedCellDef, EmbeddedSubFieldDef } from "./types";
 
 /** Computes a derived cell from its source values. Missing/non-numeric
- *  sources are treated as 0 for "sum"/"subtract"; "multiply" with any
- *  missing source returns undefined (an incomplete product isn't a
- *  meaningful partial value). Money cells are minor-unit integers — this
- *  function is unit-agnostic, it just does arithmetic on whatever numbers
- *  it's given (caller passes minor units for money, not major/float).
- *  `withDerivedCells` rounds the result to the target sub-field's declared
- *  precision afterward. */
+ *  sources: "multiply" with any missing source → undefined; "sum"/"subtract"
+ *  treat missing as 0 only when at least one source is present — if every
+ *  source is missing, return undefined (do not invent 0). Money cells are
+ *  minor-unit integers — unit-agnostic arithmetic; `withDerivedCells` rounds
+ *  to the target sub-field's declared precision afterward. */
 export function computeDerivedCellValue(
   op: EmbeddedDerivedCellDef["op"],
   values: readonly (number | undefined)[],
@@ -16,6 +14,7 @@ export function computeDerivedCellValue(
     if (values.some((value) => value === undefined)) return undefined;
     return (values as readonly number[]).reduce((product, value) => product * value, 1);
   }
+  if (values.every((value) => value === undefined)) return undefined;
   const numeric = values.map((value) => value ?? 0);
   if (op === "sum") return numeric.reduce((sum, value) => sum + value, 0);
   // subtract: first value minus every subsequent value.
@@ -60,8 +59,8 @@ function roundHalfAwayFromZero(value: number, decimals: number): number {
 /** Recomputes every derived cell of an embedded-list row from its raw
  *  values, overwriting whatever the client sent instead of merely checking
  *  it — the server is the authority for derived cells. Reads source values
- *  from the original row (never from an already-recomputed derived cell),
- *  so the iteration order of `derived` never matters. A row that isn't a
+ *  from the working copy so already-recomputed sources feed later cells;
+ *  boot-validator rejects derived-from-derived chains. A row that isn't a
  *  plain object (already invalid, or not this field's shape) passes through
  *  untouched — validation downstream rejects it. The computed value is
  *  rounded to the target sub-field's declared precision (`schema`) before
@@ -77,11 +76,13 @@ export function withDerivedCells(
   const copy: Record<string, unknown> = { ...source };
   for (const [cellName, def] of Object.entries(derived)) {
     const sourceValues = def.from.map((sourceField) => {
-      const value = source[sourceField];
+      const value = copy[sourceField];
       return typeof value === "number" ? value : undefined;
     });
     const computed = computeDerivedCellValue(def.op, sourceValues);
     if (computed === undefined) {
+      // Always clear — keeping a client value would let callers spoof required
+      // derived cells when sources are missing (server must stay authoritative).
       delete copy[cellName];
     } else {
       const target = schema[cellName];

package/src/engine/extensions/storage-provider.ts

@@ -0,0 +1,28 @@
+// Hook signature types for EXT_STORAGE_PROVIDER (tenant-destroy binary cleanup).
+//
+// Mirror of tenant-data.ts, but the destroyTenant hook takes (tenantId, ctx)
+// rather than just (ctx) — runExtensionDestroyHooks (tenant-lifecycle/stages.ts)
+// passes tenantId as its own positional arg for every EXT_*_RESOURCE-style
+// extension point, not just this one. ctx here only guarantees tenantId plus
+// the optional fileProviderResolver/log; the richer stage-runner ctx
+// (tenant-lifecycle's DestructionStageCtx) is a structural superset, so a hook
+// typed against this minimal ctx is safely assignable wherever that richer ctx
+// is passed.
+
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
+import type { TenantId } from "../types";
+
+export interface StorageProviderHookCtx {
+  readonly tenantId: TenantId;
+  readonly fileProviderResolver?: FileProviderResolver;
+  readonly log?: (message: string) => void;
+}
+
+export type StorageProviderDestroyTenantHook = (
+  tenantId: TenantId,
+  ctx: StorageProviderHookCtx,
+) => Promise<void>;
+
+export interface StorageProviderExtensionHooks {
+  readonly destroyTenant: StorageProviderDestroyTenantHook;
+}

package/src/engine/extensions/user-data.ts

@@ -66,6 +66,10 @@ export type TenantUserModel = "single-user" | "multi-user";
  */
 export interface UserDataStorageProvider {
   delete(storageKey: string): Promise<void>;
+  // Needed so a forget/tenant-destroy hook can find derived/variant keys
+  // (thumbnails, resized variants) that are never tracked anywhere but the
+  // storage layer itself — see fileRefDeleteHook.
+  list(prefix: string): Promise<readonly string[]>;
 }
 
 export interface UserDataHookCtx {

package/src/engine/feature-ast/__tests__/parse.test.ts

@@ -2588,7 +2588,7 @@ describe("cross-file registrar-wrapper resolution against a real filesystem Proj
 
   test("resolves the imported wrapper and recognises the nav pattern it registers", () => {
     expect(result.errors).toEqual([]);
-    expect(result.patterns.map((p) => p.kind)).toEqual(["nav", "requires"]);
+    expect(result.patterns.map((p) => p.kind)).toEqual(["requires", "nav"]);
   });
 
   test("the resolved pattern's source points at the imported file, not the entry file", () => {

package/src/engine/feature-ast/__tests__/patch.test.ts

@@ -391,6 +391,16 @@ describe("addPattern — error paths", () => {
     const sf = makeSourceFile("export const x = 1;");
     expect(() => addPattern(sf, newSecretPattern)).toThrow(/no defineFeature/);
   });
+
+  test("throws for ai.* kinds (must target a workflow steps array)", () => {
+    const sf = makeSourceFile(`
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+defineFeature("ai-host", (r) => {});
+`);
+    expect(() =>
+      addPattern(sf, { kind: "ai.generate", stepKey: "generate" } as FeaturePattern),
+    ).toThrow(/ai\.generate steps must be inserted into a defineWorkflow/);
+  });
 });
 
 describe("callMatchesId — positional and object-form lookups", () => {

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -869,9 +869,7 @@ describe("render → parse roundtrip — AI pipeline steps", () => {
 
   test("inline + const-ref ai steps round-trip structurally", () => {
     const aiPatterns = initial.patterns.filter((p) => p.kind.startsWith("ai."));
-    const stepCalls = aiPatterns
-      .map((p) => indent(renderPattern(p), "      ").replace(/;\s*$/, ","))
-      .join("\n");
+    const stepCalls = aiPatterns.map((p) => `${indent(renderPattern(p), "      ")},`).join("\n");
     const wrapped = `
 import { defineFeature, defineWorkflow, stepsPipeline } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";

package/src/engine/feature-ast/extractors/ai-steps.ts

@@ -1,5 +1,4 @@
-import type { CallExpression, Node, ObjectLiteralExpression, SourceFile } from "ts-morph";
-import { SyntaxKind } from "ts-morph";
+import type { CallExpression, ObjectLiteralExpression, SourceFile } from "ts-morph";
 import type {
   AiClassifyPattern,
   AiExtractPattern,
@@ -17,7 +16,10 @@ import {
   isRawRefSentinel,
   ok,
   readDataLiteralNode,
+  readNameLiteral,
+  readObjectPropertyInitializer,
   readStringOrRaw,
+  resolveSameFileObjectLiteral,
 } from "./shared";
 
 type AiStepKind = AiGeneratePattern["kind"] | AiExtractPattern["kind"] | AiClassifyPattern["kind"];
@@ -32,33 +34,11 @@ type AiStepCommonExtracted = {
   readonly paramsSchemaSource?: SourceLocation;
 };
 
-function resolveObjectLiteralArg(node: Node): ObjectLiteralExpression | undefined {
-  const direct = node.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (direct) return direct;
-  const identifier = node.asKind(SyntaxKind.Identifier);
-  if (!identifier) return undefined;
-  const varDecl = node.getSourceFile().getVariableDeclaration(identifier.getText());
-  return varDecl?.getInitializer()?.asKind(SyntaxKind.ObjectLiteralExpression);
-}
-
-function readPropertyInitializer(
-  obj: ObjectLiteralExpression,
-  propertyName: string,
-): import("ts-morph").Expression | undefined {
-  const prop = obj.getProperty(propertyName);
-  if (!prop) return undefined;
-  const assign = prop.asKind(SyntaxKind.PropertyAssignment);
-  if (assign) return assign.getInitializer();
-  const shorthand = prop.asKind(SyntaxKind.ShorthandPropertyAssignment);
-  if (shorthand) return shorthand.getNameNode();
-  return undefined;
-}
-
 function readEditableStringProp(
   obj: ObjectLiteralExpression,
   propertyName: string,
 ): string | AiStepOpaqueArgs | undefined {
-  const init = readPropertyInitializer(obj, propertyName);
+  const init = readObjectPropertyInitializer(obj, propertyName);
   if (!init) return undefined;
   const value = readStringOrRaw(init);
   if (value === undefined) return undefined;
@@ -108,7 +88,7 @@ function extractAiStepCommon(
     return fail(kind, source, "expected one argument object");
   }
 
-  const obj = resolveObjectLiteralArg(arg);
+  const obj = resolveSameFileObjectLiteral(arg);
   if (!obj) {
     if (isRawRefSentinel(readDataLiteralNode(arg))) {
       return ok({
@@ -123,15 +103,21 @@ function extractAiStepCommon(
     );
   }
 
-  const stepKey = readEditableStringProp(obj, "stepKey");
-  if (stepKey === undefined) {
+  const stepKeyInit = readObjectPropertyInitializer(obj, "stepKey");
+  if (!stepKeyInit) {
     return fail(kind, source, "missing `stepKey` property");
   }
+  // PatternId needs a concrete string — resolve identifiers like patch.readAiStepKey.
+  const stepKeyLiteral = readNameLiteral(stepKeyInit);
+  const stepKey = stepKeyLiteral ?? readStringOrRaw(stepKeyInit);
+  if (stepKey === undefined) {
+    return fail(kind, source, "`stepKey` must be a string literal or resolvable identifier");
+  }
   const promptKey = readEditableStringProp(obj, "promptKey");
   if (promptKey === undefined) {
     return fail(kind, source, "missing `promptKey` property");
   }
-  const promptFallbackInit = readPropertyInitializer(obj, "promptFallback");
+  const promptFallbackInit = readObjectPropertyInitializer(obj, "promptFallback");
   if (!promptFallbackInit) {
     return fail(kind, source, "missing `promptFallback` property");
   }
@@ -140,7 +126,7 @@ function extractAiStepCommon(
     return fail(kind, source, "`promptFallback` must be a string literal or identifier reference");
   }
 
-  const defaultsInit = readPropertyInitializer(obj, "defaults");
+  const defaultsInit = readObjectPropertyInitializer(obj, "defaults");
   if (!defaultsInit) {
     return fail(kind, source, "missing `defaults` property");
   }
@@ -149,7 +135,7 @@ function extractAiStepCommon(
     return fail(kind, source, "`defaults` could not be read as a StepPolicy literal");
   }
 
-  const paramsSchemaInit = readPropertyInitializer(obj, "paramsSchema");
+  const paramsSchemaInit = readObjectPropertyInitializer(obj, "paramsSchema");
   if (!paramsSchemaInit) {
     return fail(kind, source, "missing `paramsSchema` property");
   }
@@ -206,11 +192,11 @@ export function extractAiGenerate(
   }
 
   const arg = call.getArguments()[0];
-  const obj = arg ? resolveObjectLiteralArg(arg) : undefined;
+  const obj = arg ? resolveSameFileObjectLiteral(arg) : undefined;
   if (!obj) {
     return fail("ai.generate", common.pattern.source, "expected resolvable argument object");
   }
-  const inputInit = readPropertyInitializer(obj, "input");
+  const inputInit = readObjectPropertyInitializer(obj, "input");
   if (!inputInit) {
     return fail("ai.generate", common.pattern.source, "missing `input` property");
   }
@@ -252,16 +238,16 @@ export function extractAiExtract(
   }
 
   const arg = call.getArguments()[0];
-  const obj = arg ? resolveObjectLiteralArg(arg) : undefined;
+  const obj = arg ? resolveSameFileObjectLiteral(arg) : undefined;
   if (!obj) {
     return fail("ai.extract", common.pattern.source, "expected resolvable argument object");
   }
 
-  const outputSchemaInit = readPropertyInitializer(obj, "outputSchema");
+  const outputSchemaInit = readObjectPropertyInitializer(obj, "outputSchema");
   if (!outputSchemaInit) {
     return fail("ai.extract", common.pattern.source, "missing `outputSchema` property");
   }
-  const instructionsInit = readPropertyInitializer(obj, "instructions");
+  const instructionsInit = readObjectPropertyInitializer(obj, "instructions");
   if (!instructionsInit) {
     return fail("ai.extract", common.pattern.source, "missing `instructions` property");
   }
@@ -274,7 +260,7 @@ export function extractAiExtract(
     );
   }
 
-  const documentInit = readPropertyInitializer(obj, "document");
+  const documentInit = readObjectPropertyInitializer(obj, "document");
   let documentBody: SourceLocation | undefined;
   if (documentInit) {
     const documentFn = findFunctionLiteral(documentInit);
@@ -319,12 +305,12 @@ export function extractAiClassify(
   }
 
   const arg = call.getArguments()[0];
-  const obj = arg ? resolveObjectLiteralArg(arg) : undefined;
+  const obj = arg ? resolveSameFileObjectLiteral(arg) : undefined;
   if (!obj) {
     return fail("ai.classify", common.pattern.source, "expected resolvable argument object");
   }
 
-  const actionsInit = readPropertyInitializer(obj, "actions");
+  const actionsInit = readObjectPropertyInitializer(obj, "actions");
   if (!actionsInit) {
     return fail("ai.classify", common.pattern.source, "missing `actions` property");
   }
@@ -337,7 +323,7 @@ export function extractAiClassify(
     );
   }
 
-  const inputInit = readPropertyInitializer(obj, "input");
+  const inputInit = readObjectPropertyInitializer(obj, "input");
   if (!inputInit) {
     return fail("ai.classify", common.pattern.source, "missing `input` property");
   }

package/src/engine/feature-ast/extractors/index.ts

@@ -80,7 +80,9 @@ export {
   readDataLiteralNode,
   readNameOrRef,
   readNameOrRefOrList,
+  readObjectPropertyInitializer,
   readPropertyKey,
   readStringLiteralArgs,
   readVarargsOrArrayProp,
+  resolveSameFileObjectLiteral,
 } from "./shared";

package/src/engine/feature-ast/extractors/shared.ts

@@ -1,4 +1,4 @@
-import type { CallExpression, Node } from "ts-morph";
+import type { CallExpression, Node, ObjectLiteralExpression } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
 import { isPlainObject } from "../../../utils/is-plain-object";
 import type { ParseError } from "../parse";
@@ -264,6 +264,31 @@ export function readNameOrRef(node: Node): string | undefined {
   return undefined;
 }
 
+/** Resolve an inline object literal or a same-file `const` that initializes to one. */
+export function resolveSameFileObjectLiteral(node: Node): ObjectLiteralExpression | undefined {
+  const direct = node.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (direct) return direct;
+  const identifier = node.asKind(SyntaxKind.Identifier);
+  if (!identifier) return undefined;
+  const valueDecl = identifier.getSymbol()?.getValueDeclaration();
+  const fromSymbol = valueDecl?.asKind(SyntaxKind.VariableDeclaration);
+  const varDecl = fromSymbol ?? node.getSourceFile().getVariableDeclaration(identifier.getText());
+  return varDecl?.getInitializer()?.asKind(SyntaxKind.ObjectLiteralExpression);
+}
+
+export function readObjectPropertyInitializer(
+  obj: ObjectLiteralExpression,
+  propertyName: string,
+): import("ts-morph").Expression | undefined {
+  const prop = obj.getProperty(propertyName);
+  if (!prop) return undefined;
+  const assign = prop.asKind(SyntaxKind.PropertyAssignment);
+  if (assign) return assign.getInitializer();
+  const shorthand = prop.asKind(SyntaxKind.ShorthandPropertyAssignment);
+  if (shorthand) return shorthand.getNameNode();
+  return undefined;
+}
+
 export function findFunctionLiteral(node: Node): Node | undefined {
   if (node.getKind() === SyntaxKind.ArrowFunction) return node;
   if (node.getKind() === SyntaxKind.FunctionExpression) return node;