@kosdev-code/kos-codegen-core 3.0.20 → 3.0.22

package/index.mjs

@@ -3,7 +3,7 @@ import * as path from "path";
 import * as ejs from "ejs";
 import fg from "fast-glob";
 import prettier from "prettier";
-import { Scope, Project, QuoteKind, IndentationText, VariableDeclarationKind, Node } from "ts-morph";
+import { Scope, Project, QuoteKind, IndentationText, VariableDeclarationKind, Node, SyntaxKind } from "ts-morph";
 import * as ts from "typescript";
 class TrackingFileSystem {
   inner;
@@ -474,6 +474,84 @@ function generateSplashProject(codegenFs, templateDir, options) {
     normalized
   );
 }
+const MODEL_PROJECT_SUFFIX = "-models";
+const DEFAULT_MODEL_LIBS_DIR = "libs";
+const JSONC_ESLINT_PARSER_VERSION = "^2.1.0";
+function resolveModelProjectLayout(codegenFs, options) {
+  const base = dashCase(options.name);
+  const projectName = base.endsWith(MODEL_PROJECT_SUFFIX) ? base : `${base}${MODEL_PROJECT_SUFFIX}`;
+  const libsDir = (options.libsDir || DEFAULT_MODEL_LIBS_DIR).replace(
+    /\\/g,
+    "/"
+  );
+  const scope = codegenFs ? readNpmScope(codegenFs) : void 0;
+  return {
+    projectName,
+    projectRoot: `${libsDir}/${projectName}`.replace(/^\/+/, ""),
+    importPath: scope ? `@${scope}/${projectName}` : projectName
+  };
+}
+function readNpmScope(codegenFs) {
+  if (!codegenFs.exists("package.json")) {
+    return void 0;
+  }
+  const name = readJson(codegenFs, "package.json").name;
+  if (!name?.startsWith("@")) {
+    return void 0;
+  }
+  return name.split("/")[0].slice(1);
+}
+function offsetFromRoot(projectRoot) {
+  return projectRoot.split("/").filter(Boolean).map(() => "../").join("");
+}
+function generateModelProject(codegenFs, templateDir, options) {
+  const layout = resolveModelProjectLayout(codegenFs, options);
+  generateFilesFromTemplates(
+    codegenFs,
+    path.join(templateDir, "project"),
+    layout.projectRoot,
+    {
+      ...layout,
+      projectNameCamelCase: camelCase(layout.projectName),
+      offsetFromRoot: offsetFromRoot(layout.projectRoot),
+      template: ""
+    }
+  );
+  registerTsconfigPath(codegenFs, layout);
+  ensureJsoncEslintParser(codegenFs);
+  return layout;
+}
+function registerTsconfigPath(codegenFs, layout) {
+  if (!codegenFs.exists("tsconfig.base.json")) {
+    return;
+  }
+  updateJson(codegenFs, "tsconfig.base.json", (json) => {
+    json.compilerOptions = json.compilerOptions ?? {};
+    json.compilerOptions.paths = json.compilerOptions.paths ?? {};
+    json.compilerOptions.paths[layout.importPath] = [
+      `${layout.projectRoot}/src/index.ts`
+    ];
+    return json;
+  });
+}
+function ensureJsoncEslintParser(codegenFs) {
+  if (!codegenFs.exists("package.json")) {
+    return;
+  }
+  const pkg = readJson(codegenFs, "package.json");
+  const devDependencies = pkg.devDependencies ?? {};
+  if ("jsonc-eslint-parser" in devDependencies) {
+    return;
+  }
+  devDependencies["jsonc-eslint-parser"] = JSONC_ESLINT_PARSER_VERSION;
+  pkg.devDependencies = Object.fromEntries(
+    // Codepoint order, matching what Nx's own dependency helper produces.
+    Object.entries(devDependencies).sort(
+      ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+    )
+  );
+  writeJson(codegenFs, "package.json", pkg);
+}
 function generateInit(codegenFs, options) {
   const logger = getCodegenLogger();
   const { appProject, modelProject, registrationProject } = options;
@@ -913,7 +991,8 @@ function normalizeOptions(codegenFs, options, projects) {
   const booleanDefaults = {
     companion: false,
     skipRegistration: false,
-    futureAware: "none"
+    futureAware: "none",
+    singleton: false
   };
   return {
     ...booleanDefaults,
@@ -925,6 +1004,58 @@ function normalizeOptions(codegenFs, options, projects) {
     template: ""
   };
 }
+const UPDATE_RELEASE_VERSION_SCRIPT = `import devkit from "@nx/devkit";
+import { resolve } from "path";
+import { readFileSync, writeFileSync } from "fs";
+import prettier from "prettier";
+
+// KOS artifact versioning: stamps the project's .kos.json "version" field
+// (which kabtool bakes into the KAB). Never touches package.json.
+// Driven by tag-based releases:
+//   nx run-many --target=version --args=--ver=$KOSBUILD_VERSION
+
+const { readCachedProjectGraph } = devkit;
+const [, , name, versionArg] = process.argv;
+
+// "{args.ver}" arrives literally when the target runs without --args=--ver=<v>;
+// treat that (or a missing arg) as "report current version, change nothing".
+const version =
+  versionArg && !versionArg.startsWith("{args") ? versionArg : undefined;
+
+if (!name) {
+  console.error("usage: update-release-version.mjs <project> <version>");
+  process.exit(1);
+}
+
+const graph = readCachedProjectGraph();
+const project = graph.nodes[name];
+if (!project) {
+  console.error("Unknown project: " + name);
+  process.exit(1);
+}
+
+const kosJsonPath = resolve(process.cwd(), project.data.root, ".kos.json");
+let kosJson;
+try {
+  kosJson = JSON.parse(readFileSync(kosJsonPath, "utf8"));
+} catch {
+  console.error("Missing or invalid .kos.json: " + kosJsonPath);
+  process.exit(1);
+}
+
+if (!version) {
+  console.log(name + ": " + kosJson.version + " (no --ver given; unchanged)");
+  process.exit(0);
+}
+
+const prettierOptions = await prettier.resolveConfig(kosJsonPath);
+const output = await prettier.format(
+  JSON.stringify({ ...kosJson, version }, null, 2),
+  { ...prettierOptions, parser: "json" }
+);
+writeFileSync(kosJsonPath, output);
+console.log(name + ": version -> " + version);
+`;
 function transformSourceFile(codegenFs, filePath, mutate) {
   const content = codegenFs.read(filePath);
   if (content === null) {
@@ -953,6 +1084,15 @@ function readSourceFile(codegenFs, filePath, inspect) {
     project.createSourceFile(filePath, content, { overwrite: true })
   );
 }
+function decoratorConfigText(sourceFile, cls, decoratorName) {
+  const arg = cls.getDecorator(decoratorName)?.getArguments()[0];
+  if (!arg) return void 0;
+  if (arg.getKindName() === "ObjectLiteralExpression") return arg.getText();
+  const text = arg.getText().trim();
+  if (!/^[A-Za-z_$][\w$]*$/.test(text)) return text;
+  const initializer = sourceFile.getVariableDeclaration(text)?.getInitializer()?.getText();
+  return initializer ? initializer.replace(/\s+as\s+const\s*$/, "") : text;
+}
 function ensureNamedImport(sourceFile, moduleSpecifier, names) {
   const decls = sourceFile.getImportDeclarations().filter((d) => d.getModuleSpecifierValue() === moduleSpecifier);
   const existing = /* @__PURE__ */ new Set();
@@ -1066,7 +1206,8 @@ function ensureConstCatalogEntry(sourceFile, spec) {
     }
     literal.addPropertyAssignment({
       name: spec.key,
-      initializer: spec.initializer
+      initializer: spec.initializer,
+      leadingTrivia: spec.leadingTrivia
     });
     return { key: spec.key, created: true };
   }
@@ -1084,7 +1225,8 @@ function ensureConstCatalogEntry(sourceFile, spec) {
   }
   literal.addPropertyAssignment({
     name: spec.key,
-    initializer: spec.initializer
+    initializer: spec.initializer,
+    leadingTrivia: spec.leadingTrivia
   });
   return { key: spec.key, created: true };
 }
@@ -1093,7 +1235,8 @@ function ensureExportedTypeAlias(sourceFile, spec) {
   sourceFile.addTypeAlias({
     name: spec.name,
     type: spec.type,
-    isExported: true
+    isExported: true,
+    docs: spec.docs ? [spec.docs] : void 0
   });
   return true;
 }
@@ -1117,12 +1260,47 @@ function ensureBarrelExport(sourceFile, moduleSpecifier) {
   sourceFile.addExportDeclaration({ moduleSpecifier });
   return true;
 }
+function ensureNamedExports(sourceFile, moduleSpecifier, names, isTypeOnly = false) {
+  const existing = sourceFile.getExportDeclarations().find(
+    (d) => d.getModuleSpecifierValue() === moduleSpecifier && d.isTypeOnly() === isTypeOnly
+  );
+  if (!existing) {
+    sourceFile.addExportDeclaration({
+      moduleSpecifier,
+      isTypeOnly,
+      namedExports: names.map((name) => {
+        return { name };
+      })
+    });
+    return true;
+  }
+  const present = new Set(existing.getNamedExports().map((e) => e.getName()));
+  const missing = names.filter((name) => !present.has(name));
+  if (missing.length === 0) return false;
+  existing.addNamedExports(
+    missing.map((name) => {
+      return { name };
+    })
+  );
+  return true;
+}
+function ensureExportedInterface(sourceFile, name, properties = [], extendsTypes = []) {
+  if (sourceFile.getInterface(name)) return false;
+  sourceFile.addInterface({
+    name,
+    isExported: true,
+    extends: extendsTypes,
+    properties
+  });
+  return true;
+}
 function addDecoratedMethod(cls, spec) {
   if (cls.getMethod(spec.name)) return false;
   cls.addMethod({
     name: spec.name,
     isAsync: spec.isAsync,
     returnType: spec.returnType,
+    docs: spec.docs ? [spec.docs] : void 0,
     parameters: spec.parameters?.map((p) => {
       return { name: p.name, type: p.type, hasQuestionToken: p.optional };
     }),
@@ -1130,6 +1308,7 @@ function addDecoratedMethod(cls, spec) {
     decorators: [
       {
         name: spec.decoratorName,
+        typeArguments: spec.decoratorTypeArgs,
         arguments: spec.decoratorArgsText ? [spec.decoratorArgsText] : []
       }
     ]
@@ -1212,17 +1391,28 @@ function listServiceCatalog(codegenFs, query, projects) {
       app,
       version,
       serviceModulePath: posix,
-      operations: readOperations(codegenFs, openapiPath)
+      operations: readOperations(codegenFs, openapiPath) ?? []
     });
   }
   return entries.sort(
     (a, b) => a.app.localeCompare(b.app) || a.version.localeCompare(b.version)
   );
 }
+function readServiceModuleOperations(codegenFs, serviceModuleFile) {
+  const moduleFile = serviceModuleFile.endsWith(".ts") ? serviceModuleFile : `${serviceModuleFile}.ts`;
+  const posix = moduleFile.split(path.sep).join("/");
+  const openapiPath = posix.replace(/service\.ts$/, "openapi.d.ts");
+  for (const candidate of [openapiPath, posix]) {
+    if (!codegenFs.exists(candidate)) continue;
+    const operations = readOperations(codegenFs, candidate);
+    if (operations) return operations;
+  }
+  return null;
+}
 function readOperations(codegenFs, openapiPath) {
   return readSourceFile(codegenFs, openapiPath, (sf) => {
     const paths = sf.getInterface("paths");
-    if (!paths) return [];
+    if (!paths) return null;
     const operations = [];
     for (const pathProp of paths.getProperties()) {
       const servicePath = unquote(pathProp.getName());
@@ -1256,58 +1446,6 @@ function readSummary(methodProp) {
 function unquote(name) {
   return name.replace(/^["']|["']$/g, "");
 }
-const UPDATE_RELEASE_VERSION_SCRIPT = `import devkit from "@nx/devkit";
-import { resolve } from "path";
-import { readFileSync, writeFileSync } from "fs";
-import prettier from "prettier";
-
-// KOS artifact versioning: stamps the project's .kos.json "version" field
-// (which kabtool bakes into the KAB). Never touches package.json.
-// Driven by tag-based releases:
-//   nx run-many --target=version --args=--ver=$KOSBUILD_VERSION
-
-const { readCachedProjectGraph } = devkit;
-const [, , name, versionArg] = process.argv;
-
-// "{args.ver}" arrives literally when the target runs without --args=--ver=<v>;
-// treat that (or a missing arg) as "report current version, change nothing".
-const version =
-  versionArg && !versionArg.startsWith("{args") ? versionArg : undefined;
-
-if (!name) {
-  console.error("usage: update-release-version.mjs <project> <version>");
-  process.exit(1);
-}
-
-const graph = readCachedProjectGraph();
-const project = graph.nodes[name];
-if (!project) {
-  console.error("Unknown project: " + name);
-  process.exit(1);
-}
-
-const kosJsonPath = resolve(process.cwd(), project.data.root, ".kos.json");
-let kosJson;
-try {
-  kosJson = JSON.parse(readFileSync(kosJsonPath, "utf8"));
-} catch {
-  console.error("Missing or invalid .kos.json: " + kosJsonPath);
-  process.exit(1);
-}
-
-if (!version) {
-  console.log(name + ": " + kosJson.version + " (no --ver given; unchanged)");
-  process.exit(0);
-}
-
-const prettierOptions = await prettier.resolveConfig(kosJsonPath);
-const output = await prettier.format(
-  JSON.stringify({ ...kosJson, version }, null, 2),
-  { ...prettierOptions, parser: "json" }
-);
-writeFileSync(kosJsonPath, output);
-console.log(name + ": version -> " + version);
-`;
 function appendBarrelExport(codegenFs, indexPath, exportPath) {
   const exportLine = `export * from '${exportPath}'`;
   const content = codegenFs.read(indexPath) ?? "";
@@ -1354,10 +1492,57 @@ function updateModelIndex(codegenFs, indexPath, modelPath) {
   const newContents = printer.printFile(updatedSourceFile);
   codegenFs.write(indexPath, newContents);
 }
-function generateHook(codegenFs, templateDir, options, cwd, projects) {
-  if (!options.appProject) {
-    throw new Error("No app project specified");
+function generateCompanionModel(codegenFs, templateDir, options, projects) {
+  const logger = getCodegenLogger();
+  const normalized = normalizeAllValues({
+    companionModelName: options.companionModelName,
+    modelName: options.modelName
+  });
+  const companionChildKosConfig = getKosProjectConfiguration(
+    codegenFs,
+    options.companionModelProject,
+    projects
+  );
+  const parentProject = findProjectByName(
+    codegenFs.root,
+    options.modelProject,
+    projects
+  );
+  const childProject = findProjectByName(
+    codegenFs.root,
+    options.companionModelProject,
+    projects
+  );
+  const projectRoot = childProject?.sourceRoot;
+  if (!projectRoot) {
+    logger.warn(`Companion child project source root not found`);
+    return;
+  }
+  let importPath = "";
+  if (parentProject) {
+    const pkgJsonPath = path.join(parentProject.root, "package.json");
+    try {
+      const pkgJson = readJson(codegenFs, pkgJsonPath);
+      importPath = pkgJson.name || "";
+    } catch {
+      importPath = "";
+    }
   }
+  const modelLocation = companionChildKosConfig?.generator?.defaults?.model?.folder || "";
+  const filePath = path.join(
+    projectRoot,
+    modelLocation,
+    normalized.companionModelNameDashCase
+  );
+  logger.info(`Generating companion model in ${filePath}`);
+  generateFilesFromTemplates(codegenFs, templateDir, filePath, {
+    ...options,
+    ...normalized,
+    importPath
+  });
+}
+function generateContainerModel(codegenFs, templateDir, options, cwd, projects) {
+  const logger = getCodegenLogger();
   const currentProject = getProject(codegenFs, cwd);
   const modelProjectName = options.modelProject || currentProject?.name;
   if (!modelProjectName) {
@@ -1365,56 +1550,109 @@ function generateHook(codegenFs, templateDir, options, cwd, projects) {
       "No model project found. Please specify a model project with --modelProject."
     );
   }
-  const modelName = options.name || getCurrentDirectoryName(cwd);
+  const modelName = options.modelName || getCurrentDirectoryName(cwd);
   if (!modelName) {
     throw new Error(
       "No model name found. Please specify a model name with --name."
     );
   }
-  const kosModelConfig = getKosModelConfiguration(
-    codegenFs,
-    modelProjectName,
-    modelName,
-    projects
-  );
-  options.singleton = kosModelConfig ? !!kosModelConfig.singleton : false;
-  options.name = modelName;
-  options.modelProject = modelProjectName;
+  options.modelName = modelName;
+  options.name = `${modelName}-container`;
   const normalized = normalizeOptions(codegenFs, options, projects);
-  const appProject = findProjectByName(
+  const projectConfig = findProjectByName(
     codegenFs.root,
-    normalized.appProject,
+    normalized.modelProject,
     projects
   );
-  if (!appProject) {
-    throw new Error(`App project '${normalized.appProject}' not found`);
+  if (!projectConfig) {
+    throw new Error(`Model project '${normalized.modelProject}' not found`);
   }
+  addKosModelConfiguration({
+    codegenFs,
+    modelName: normalized.nameDashCase,
+    projectName: projectConfig.name,
+    projectRoot: projectConfig.root,
+    singleton: !!options.singleton,
+    container: true,
+    // The container's exported registration bean (`export const <ProperCase>`).
+    factory: normalized.nameProperCase
+  });
   const kosConfig = getKosProjectConfiguration(
     codegenFs,
-    appProject.name,
+    projectConfig.name,
     projects
   );
-  const componentLocation = kosConfig?.generator?.defaults?.component?.folder || "";
-  options.appDirectory = options.appDirectory || componentLocation;
-  const projectRoot = appProject.sourceRoot;
+  const modelLocation = kosConfig?.generator?.defaults?.model?.folder || "";
+  const internal = !!kosConfig?.generator?.internal;
+  options.modelDirectory = options.modelDirectory || modelLocation;
+  const projectRoot = projectConfig.sourceRoot;
   if (projectRoot) {
-    generateFilesFromTemplates(
-      codegenFs,
-      templateDir,
-      path.join(
-        projectRoot,
-        options.appDirectory,
-        "hooks",
-        normalized.nameDashCase
-      ),
-      normalized
+    logger.info(
+      `Generating container model ${normalized.nameDashCase} in ${projectRoot}`
     );
-    appendBarrelExport(
-      codegenFs,
-      path.join(projectRoot, options.appDirectory, "hooks", "index.ts"),
-      `./${normalized.nameDashCase}`
+    const modelNameDashCase = normalized.modelNameDashCase || normalized.nameDashCase;
+    const modelFolder = path.join(
+      projectRoot,
+      options.modelDirectory || "",
+      modelNameDashCase
+    );
+    if (options.existingModel) {
+      addContainerToExistingModelFolder(codegenFs, templateDir, modelFolder, {
+        ...normalized,
+        internal
+      });
+    } else {
+      generateFilesFromTemplates(
+        codegenFs,
+        path.join(templateDir, "model"),
+        modelFolder,
+        { ...normalized, internal }
+      );
+    }
+    const modelIndex = path.join(projectRoot, "index.ts");
+    const modelPath = normalized.modelDirectory ? `${normalized.modelDirectory}/${modelNameDashCase}` : modelNameDashCase;
+    updateModelIndex(codegenFs, modelIndex, modelPath);
+  }
+}
+function addContainerToExistingModelFolder(codegenFs, templateDir, modelFolder, substitutions) {
+  const containerFileName = `${substitutions.nameDashCase}-model.ts`;
+  const containerTemplate = path.join(
+    templateDir,
+    "model",
+    "__nameDashCase__-model.ts.template"
+  );
+  const rendered = ejs.render(
+    fs.readFileSync(containerTemplate, "utf-8"),
+    substitutions,
+    { filename: containerTemplate }
+  );
+  codegenFs.write(path.join(modelFolder, containerFileName), rendered);
+  const typesPath = path.join(modelFolder, "types", "index.d.ts");
+  if (codegenFs.read(typesPath) === null) {
+    codegenFs.write(typesPath, "");
+  }
+  transformSourceFile(codegenFs, typesPath, (sourceFile) => {
+    ensureExportedInterface(
+      sourceFile,
+      `${substitutions.nameProperCase}Options`
     );
+  });
+  const barrelPath = path.join(modelFolder, "index.ts");
+  if (codegenFs.read(barrelPath) === null) {
+    codegenFs.write(barrelPath, "");
   }
+  transformSourceFile(codegenFs, barrelPath, (sourceFile) => {
+    const moduleSpecifier = `./${containerFileName.replace(/\.ts$/, "")}`;
+    ensureNamedExports(sourceFile, moduleSpecifier, [
+      substitutions.nameProperCase
+    ]);
+    ensureNamedExports(
+      sourceFile,
+      moduleSpecifier,
+      [`${substitutions.nameProperCase}Model`],
+      true
+    );
+  });
 }
 function generateContext(codegenFs, templateDir, options, cwd, projects) {
   if (!options.appProject) {
@@ -1468,8 +1706,10 @@ function generateContext(codegenFs, templateDir, options, cwd, projects) {
     );
   }
 }
-function generateContainerModel(codegenFs, templateDir, options, cwd, projects) {
-  const logger = getCodegenLogger();
+function generateHook(codegenFs, templateDir, options, cwd, projects) {
+  if (!options.appProject) {
+    throw new Error("No app project specified");
+  }
   const currentProject = getProject(codegenFs, cwd);
   const modelProjectName = options.modelProject || currentProject?.name;
   if (!modelProjectName) {
@@ -1477,106 +1717,56 @@ function generateContainerModel(codegenFs, templateDir, options, cwd, projects)
       "No model project found. Please specify a model project with --modelProject."
     );
   }
-  const modelName = options.modelName || getCurrentDirectoryName(cwd);
+  const modelName = options.name || getCurrentDirectoryName(cwd);
   if (!modelName) {
     throw new Error(
       "No model name found. Please specify a model name with --name."
     );
   }
-  options.modelName = modelName;
-  options.name = `${modelName}-container`;
+  const kosModelConfig = getKosModelConfiguration(
+    codegenFs,
+    modelProjectName,
+    modelName,
+    projects
+  );
+  options.singleton = kosModelConfig ? !!kosModelConfig.singleton : false;
+  options.name = modelName;
+  options.modelProject = modelProjectName;
   const normalized = normalizeOptions(codegenFs, options, projects);
-  const projectConfig = findProjectByName(
+  const appProject = findProjectByName(
     codegenFs.root,
-    normalized.modelProject,
+    normalized.appProject,
     projects
   );
-  if (!projectConfig) {
-    throw new Error(`Model project '${normalized.modelProject}' not found`);
+  if (!appProject) {
+    throw new Error(`App project '${normalized.appProject}' not found`);
   }
-  addKosModelConfiguration({
-    codegenFs,
-    modelName: normalized.nameDashCase,
-    projectName: projectConfig.name,
-    projectRoot: projectConfig.root,
-    singleton: !!options.singleton,
-    container: true,
-    // The container's exported registration bean (`export const <ProperCase>`).
-    factory: normalized.nameProperCase
-  });
   const kosConfig = getKosProjectConfiguration(
     codegenFs,
-    projectConfig.name,
+    appProject.name,
     projects
   );
-  const modelLocation = kosConfig?.generator?.defaults?.model?.folder || "";
-  const internal = !!kosConfig?.generator?.internal;
-  options.modelDirectory = options.modelDirectory || modelLocation;
-  const projectRoot = projectConfig.sourceRoot;
+  const componentLocation = kosConfig?.generator?.defaults?.component?.folder || "";
+  options.appDirectory = options.appDirectory || componentLocation;
+  const projectRoot = appProject.sourceRoot;
   if (projectRoot) {
-    logger.info(
-      `Generating container model ${normalized.nameDashCase} in ${projectRoot}`
-    );
-    const modelNameDashCase = normalized.modelNameDashCase || normalized.nameDashCase;
     generateFilesFromTemplates(
       codegenFs,
-      path.join(templateDir, "model"),
-      path.join(projectRoot, options.modelDirectory || "", modelNameDashCase),
-      { ...normalized, internal }
+      templateDir,
+      path.join(
+        projectRoot,
+        options.appDirectory,
+        "hooks",
+        normalized.nameDashCase
+      ),
+      normalized
+    );
+    appendBarrelExport(
+      codegenFs,
+      path.join(projectRoot, options.appDirectory, "hooks", "index.ts"),
+      `./${normalized.nameDashCase}`
     );
-    const modelIndex = path.join(projectRoot, "index.ts");
-    const modelPath = normalized.modelDirectory ? `${normalized.modelDirectory}/${modelNameDashCase}` : modelNameDashCase;
-    updateModelIndex(codegenFs, modelIndex, modelPath);
-  }
-}
-function generateCompanionModel(codegenFs, templateDir, options, projects) {
-  const logger = getCodegenLogger();
-  const normalized = normalizeAllValues({
-    companionModelName: options.companionModelName,
-    modelName: options.modelName
-  });
-  const companionChildKosConfig = getKosProjectConfiguration(
-    codegenFs,
-    options.companionModelProject,
-    projects
-  );
-  const parentProject = findProjectByName(
-    codegenFs.root,
-    options.modelProject,
-    projects
-  );
-  const childProject = findProjectByName(
-    codegenFs.root,
-    options.companionModelProject,
-    projects
-  );
-  const projectRoot = childProject?.sourceRoot;
-  if (!projectRoot) {
-    logger.warn(`Companion child project source root not found`);
-    return;
-  }
-  let importPath = "";
-  if (parentProject) {
-    const pkgJsonPath = path.join(parentProject.root, "package.json");
-    try {
-      const pkgJson = readJson(codegenFs, pkgJsonPath);
-      importPath = pkgJson.name || "";
-    } catch {
-      importPath = "";
-    }
   }
-  const modelLocation = companionChildKosConfig?.generator?.defaults?.model?.folder || "";
-  const filePath = path.join(
-    projectRoot,
-    modelLocation,
-    normalized.companionModelNameDashCase
-  );
-  logger.info(`Generating companion model in ${filePath}`);
-  generateFilesFromTemplates(codegenFs, templateDir, filePath, {
-    ...options,
-    ...normalized,
-    importPath
-  });
 }
 function generateModel(params) {
   const {
@@ -1675,6 +1865,55 @@ function generateModel(params) {
     );
   }
 }
+const DECLARATION_MARKER = "@kosModel";
+function findModelDeclarationFile(codegenFs, searchRoot, typeIds) {
+  const wanted = new Set(typeIds.filter(Boolean));
+  if (wanted.size === 0) return null;
+  const matches = [];
+  for (const filePath of codegenFs.listFiles(searchRoot)) {
+    if (!filePath.endsWith(".ts") || filePath.endsWith(".d.ts")) continue;
+    const content = codegenFs.read(filePath);
+    if (!content || !content.includes(DECLARATION_MARKER)) continue;
+    const declared = readDeclaredModelType(codegenFs, filePath);
+    if (declared && wanted.has(declared)) matches.push(filePath);
+  }
+  if (matches.length === 0) return null;
+  if (matches.length > 1) {
+    throw new Error(
+      `Model type '${[...wanted].join("' / '")}' is declared in more than one file:
+` + matches.sort().map((c) => `  - ${c}`).join("\n") + `
+Pass modelPath to pick one.`
+    );
+  }
+  return matches[0];
+}
+function readDeclaredModelType(codegenFs, filePath) {
+  try {
+    return readSourceFile(codegenFs, filePath, (sf) => {
+      const cls = sf.getClasses().find((c) => c.getDecorator("kosModel"));
+      if (!cls) return void 0;
+      const config = decoratorConfigText(sf, cls, "kosModel");
+      const inner = config?.startsWith("{") ? modelTypeIdProperty(config) : config;
+      if (!inner) return void 0;
+      return resolveToStringLiteral(inner.trim(), sf.getFullText());
+    });
+  } catch {
+    return void 0;
+  }
+}
+function modelTypeIdProperty(objectText) {
+  const m = objectText.match(/\bmodelTypeId\s*:\s*([^,}]+)/);
+  return m ? m[1] : void 0;
+}
+function resolveToStringLiteral(expression, fileText) {
+  const literal = expression.match(/^["'`](.*)["'`]$/);
+  if (literal) return literal[1];
+  if (!/^[A-Za-z_$][\w$]*$/.test(expression)) return void 0;
+  const declared = fileText.match(
+    new RegExp(`\\b(?:const|let|var)\\s+${expression}\\s*(?::[^=]+)?=\\s*["'\`]([^"'\`]+)["'\`]`)
+  );
+  return declared ? declared[1] : void 0;
+}
 function resolveModelFilePath(codegenFs, query, projects) {
   const kosConfig = getKosProjectConfiguration(
     codegenFs,
@@ -1709,14 +1948,23 @@ function resolveModelFilePath(codegenFs, query, projects) {
   if (codegenFs.exists(modelFilePath)) {
     return { modelFilePath, internal, sourceRoot };
   }
+  const searchRoot = path.join(sourceRoot, modelLocation);
   const discovered = findModelFileByName(
     codegenFs,
-    path.join(sourceRoot, modelLocation),
+    searchRoot,
     modelNameDashCase
   );
   if (discovered) {
     return { modelFilePath: discovered, internal, sourceRoot };
   }
+  const declaredType = kosConfig?.models?.[query.modelName]?.type;
+  const byDeclaration = findModelDeclarationFile(codegenFs, searchRoot, [
+    query.modelName,
+    ...declaredType ? [declaredType] : []
+  ]);
+  if (byDeclaration) {
+    return { modelFilePath: byDeclaration, internal, sourceRoot };
+  }
   return { modelFilePath, internal, sourceRoot };
 }
 function findModelFileByName(codegenFs, searchRoot, modelNameDashCase) {
@@ -1732,6 +1980,150 @@ Pass modelPath to pick one.`
   }
   return candidates[0];
 }
+function resolveChildModelType(codegenFs, query, projects) {
+  const childProject = query.childModelProject || query.modelProject;
+  const childType = `${properCase(query.childModel)}Model`;
+  if (childProject !== query.modelProject) {
+    const project = findProjectByName(codegenFs.root, childProject, projects);
+    const pkgJson = project ? readJson(
+      codegenFs,
+      path.join(project.root, "package.json")
+    ) : void 0;
+    return { childType, childTypeModule: pkgJson?.name };
+  }
+  const { modelFilePath: childFilePath } = resolveModelFilePath(
+    codegenFs,
+    { modelName: query.childModel, modelProject: childProject },
+    projects
+  );
+  const relative = path.relative(path.dirname(query.modelFilePath), childFilePath).replace(/\.ts$/, "");
+  return {
+    childType,
+    childTypeModule: relative.startsWith(".") ? relative : `./${relative}`
+  };
+}
+function generateViewModel(codegenFs, templateDir, options, cwd, projects) {
+  const logger = getCodegenLogger();
+  if (!options.name) {
+    throw new Error(
+      "No ViewModel name found. Please specify a name with --name."
+    );
+  }
+  const currentProject = getProject(codegenFs, cwd);
+  const modelProjectName = options.modelProject || currentProject?.name;
+  if (!modelProjectName) {
+    throw new Error(
+      "No model project found. Please specify a model project with --project."
+    );
+  }
+  const normalized = normalizeOptions(
+    codegenFs,
+    { ...options, modelProject: modelProjectName },
+    projects
+  );
+  const projectConfig = findProjectByName(
+    codegenFs.root,
+    modelProjectName,
+    projects
+  );
+  if (!projectConfig) {
+    throw new Error(`Model project '${modelProjectName}' not found`);
+  }
+  const kosConfig = getKosProjectConfiguration(
+    codegenFs,
+    projectConfig.name,
+    projects
+  );
+  const modelDirectory = options.modelDirectory || kosConfig?.generator?.defaults?.model?.folder || "";
+  const internal = !!kosConfig?.generator?.internal;
+  const projectRoot = projectConfig.sourceRoot || path.join(projectConfig.root, "src");
+  const viewModelFolder = path.join(
+    projectRoot,
+    modelDirectory,
+    normalized.nameDashCase
+  );
+  const viewModelFilePath = path.join(
+    viewModelFolder,
+    `${normalized.nameDashCase}-view-model.ts`
+  );
+  if (codegenFs.exists(viewModelFilePath)) {
+    logger.info(`ViewModel already exists: ${viewModelFilePath}`);
+    return { viewModelFilePath, created: false };
+  }
+  const resolved = (options.models || []).map(
+    (source) => resolveSourceModel(
+      codegenFs,
+      source,
+      viewModelFilePath,
+      modelProjectName,
+      projects
+    )
+  );
+  logger.info(
+    `Generating ViewModel ${normalized.nameDashCase} in ${projectRoot}`
+  );
+  const constructorParams = resolved.map(({ name, type }) => ({ name, type }));
+  generateFilesFromTemplates(codegenFs, templateDir, viewModelFolder, {
+    ...normalized,
+    internal,
+    typeId: options.typeId || normalized.nameDashCase,
+    devToolsEnabled: !!options.devToolsEnabled,
+    constructorParams,
+    constructorArgs: constructorParams.map((param) => param.name).join(", "),
+    modelImports: groupImports(resolved)
+  });
+  updateModelIndex(
+    codegenFs,
+    path.join(projectRoot, "index.ts"),
+    modelDirectory ? `${modelDirectory}/${normalized.nameDashCase}` : normalized.nameDashCase
+  );
+  return { viewModelFilePath, created: true };
+}
+function resolveSourceModel(codegenFs, source, viewModelFilePath, modelProject, projects) {
+  const sourceProject = source.project || modelProject;
+  if (sourceProject === modelProject) {
+    const { modelFilePath } = resolveModelFilePath(
+      codegenFs,
+      { modelName: source.model, modelProject: sourceProject },
+      projects
+    );
+    if (!codegenFs.exists(modelFilePath)) {
+      throw new Error(
+        `Model '${source.model}' not found in project '${sourceProject}' (looked for ${modelFilePath})`
+      );
+    }
+  } else if (!findProjectByName(codegenFs.root, sourceProject, projects)) {
+    throw new Error(`Model project '${sourceProject}' not found`);
+  }
+  const { childType, childTypeModule } = resolveChildModelType(
+    codegenFs,
+    {
+      modelFilePath: viewModelFilePath,
+      modelProject,
+      childModel: source.model,
+      childModelProject: sourceProject
+    },
+    projects
+  );
+  return {
+    name: camelCase(source.model),
+    type: childType,
+    module: childTypeModule
+  };
+}
+function groupImports(resolved) {
+  const byModule = /* @__PURE__ */ new Map();
+  for (const { type, module } of resolved) {
+    if (!module) continue;
+    const types = byModule.get(module);
+    if (!types) {
+      byModule.set(module, [type]);
+    } else if (!types.includes(type)) {
+      types.push(type);
+    }
+  }
+  return [...byModule].map(([module, types]) => ({ module, types }));
+}
 function modelBaseName(modelFilePath, modelName) {
   const base = path.basename(modelFilePath);
   const match = base.match(/^(.*)-model\.ts$/);
@@ -1744,7 +2136,7 @@ function servicesFilePathFor(modelFilePath, modelBase) {
     `${modelBase}-services.ts`
   );
 }
-function header(modelBase) {
+function header$1(modelBase) {
   return `/**
  * Service layer for the ${modelBase} model: the endpoints it calls and the
  * types derived from them. Standalone service functions for callers outside a
@@ -1755,7 +2147,7 @@ function header(modelBase) {
 function ensureServicesModule(codegenFs, modelFilePath, modelBase) {
   const servicesFilePath = servicesFilePathFor(modelFilePath, modelBase);
   if (!codegenFs.exists(servicesFilePath)) {
-    codegenFs.write(servicesFilePath, header(modelBase));
+    codegenFs.write(servicesFilePath, header$1(modelBase));
   }
   const barrelPath = path.join(path.dirname(servicesFilePath), "index.ts");
   if (!codegenFs.exists(barrelPath)) {
@@ -2240,11 +2632,25 @@ function buildDecoratorArgs(options) {
 }
 function addContainerSupportToModel(codegenFs, options, projects) {
   const logger = getCodegenLogger();
-  const childType = options.childType?.trim() || "IKosDataModel";
   const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
   if (!codegenFs.exists(modelFilePath)) {
     throw new Error(`Model file not found: ${modelFilePath}`);
   }
+  const resolvedChild = options.childModel ? resolveChildModelType(
+    codegenFs,
+    {
+      modelFilePath,
+      modelProject: options.modelProject,
+      childModel: options.childModel,
+      childModelProject: options.childModelProject
+    },
+    projects
+  ) : {
+    childType: options.childType,
+    childTypeModule: options.childTypeModule
+  };
+  const childType = resolvedChild.childType?.trim() || "IKosDataModel";
+  const childTypeModule = resolvedChild.childTypeModule;
   logger.info(
     `Adding container support (<${childType}>) to model: ${options.modelName}`
   );
@@ -2256,6 +2662,10 @@ function addContainerSupportToModel(codegenFs, options, projects) {
     ]);
     if (childType === "IKosDataModel") {
       ensureNamedImport(sf, sdk, [{ name: "IKosDataModel", isTypeOnly: true }]);
+    } else if (childTypeModule) {
+      ensureNamedImport(sf, childTypeModule, [
+        { name: childType, isTypeOnly: true }
+      ]);
     }
     const cls = getModelClass(sf);
     const className = cls.getName();
@@ -2285,38 +2695,172 @@ function addContainerSupportToModel(codegenFs, options, projects) {
   });
   return { modelFilePath };
 }
-function addModelEffectToModel(codegenFs, options, projects) {
+function addParentAwareToModel(codegenFs, options, projects) {
   const logger = getCodegenLogger();
   const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
   if (!codegenFs.exists(modelFilePath)) {
     throw new Error(`Model file not found: ${modelFilePath}`);
   }
-  logger.info(
-    `Adding @kosModelEffect "${options.methodName}" to ${options.modelName}`
-  );
+  logger.info(`Adding parent awareness to model: ${options.modelName}`);
+  let optionsTypeName;
   transformSourceFile(codegenFs, modelFilePath, (sf) => {
     const sdk = resolveSdkModuleSpecifier(sf);
-    ensureNamedImport(sf, sdk, [{ name: "kosModelEffect" }]);
+    ensureNamedImport(sf, sdk, [{ name: "kosParentAware" }]);
     const cls = getModelClass(sf);
-    const modelType = (cls.getName() ?? "").replace(/Impl$/, "");
-    addDecoratedMethod(cls, {
-      name: options.methodName,
-      decoratorName: "kosModelEffect",
-      decoratorArgsText: `{ dependencies: (model: ${modelType}) => [] }`,
-      isAsync: true,
-      returnType: "Promise<void>",
-      statements: "// TODO: react to the tracked dependencies"
+    addClassDecorator(cls, "kosParentAware", {
+      argsText: options.parentId ? `{ parentId: ${JSON.stringify(options.parentId)} }` : ""
     });
+    const ctor = cls.getConstructors()[0];
+    optionsTypeName = ctor?.getParameters()[1]?.getTypeNode()?.getText()?.replace(/<.*$/, "");
   });
-  return { modelFilePath };
+  const optionsFilePath = optionsTypeName ? extendOptionsInterface(codegenFs, modelFilePath, optionsTypeName, logger) : void 0;
+  return { modelFilePath, optionsFilePath };
 }
-const FRAMEWORK_TYPES$1 = /* @__PURE__ */ new Set(["IKosDataModel", "IKosIdentifiable"]);
-function addDependencyToModel(codegenFs, options, projects) {
-  const logger = getCodegenLogger();
-  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
-  if (!codegenFs.exists(modelFilePath)) {
-    throw new Error(`Model file not found: ${modelFilePath}`);
-  }
+function extendOptionsInterface(codegenFs, modelFilePath, optionsTypeName, logger) {
+  const typesPath = path.join(
+    path.dirname(modelFilePath),
+    "types",
+    "index.d.ts"
+  );
+  const target = codegenFs.exists(typesPath) ? typesPath : modelFilePath;
+  let extended = false;
+  transformSourceFile(codegenFs, target, (sf) => {
+    const iface = sf.getInterface(optionsTypeName);
+    if (!iface) return;
+    const already = iface.getExtends().some((clause) => clause.getText().includes("KosParentAware"));
+    if (already) {
+      extended = true;
+      return;
+    }
+    ensureNamedImport(sf, "@kosdev-code/kos-ui-sdk", [
+      { name: "KosParentAware", isTypeOnly: true }
+    ]);
+    iface.addExtends("KosParentAware");
+    extended = true;
+  });
+  if (!extended) {
+    logger.warn(
+      `Could not find interface ${optionsTypeName}; add "extends KosParentAware" to it by hand.`
+    );
+    return void 0;
+  }
+  return target;
+}
+function firstDecoratorArg(decoratorText) {
+  const open = decoratorText.indexOf("(");
+  if (open === -1) return void 0;
+  const inner = decoratorText.slice(open + 1, decoratorText.lastIndexOf(")")).replace(/\s+/g, " ").trim();
+  return inner || void 0;
+}
+function collectDecorated(cls, decoratorName) {
+  const members = [];
+  const visit = (name, decoratorTextOf, typeText) => {
+    const text = decoratorTextOf();
+    if (text === void 0) return;
+    members.push({
+      name,
+      arg: firstDecoratorArg(text),
+      type: typeText || void 0
+    });
+  };
+  for (const m of cls.getMethods()) {
+    const dec = m.getDecorator(decoratorName);
+    if (dec) {
+      visit(m.getName(), () => dec.getText(), m.getReturnTypeNode()?.getText());
+    }
+  }
+  for (const p of cls.getProperties()) {
+    const dec = p.getDecorator(decoratorName);
+    if (dec) {
+      visit(p.getName(), () => dec.getText(), p.getTypeNode()?.getText());
+    }
+  }
+  return members;
+}
+function describeModel(codegenFs, options, projects) {
+  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
+  const content = codegenFs.read(modelFilePath);
+  if (content === null) {
+    throw new Error(`Model file not found: ${modelFilePath}`);
+  }
+  const project = new Project({ useInMemoryFileSystem: true });
+  const sf = project.createSourceFile(modelFilePath, content, {
+    overwrite: true
+  });
+  let modelType;
+  const modelTypeDecl = sf.getVariableDeclaration("MODEL_TYPE");
+  if (modelTypeDecl) {
+    const init = modelTypeDecl.getInitializer()?.getText();
+    if (init) modelType = init.replace(/^["'`]|["'`]$/g, "");
+  }
+  const cls = sf.getClasses().find((c) => c.getDecorator("kosModel")) ?? sf.getClasses().find((c) => c.isExported()) ?? sf.getClasses()[0];
+  if (!cls) {
+    return {
+      modelFilePath,
+      modelType,
+      classDecorators: [],
+      singleton: false,
+      isCompanion: false,
+      children: [],
+      dependencies: [],
+      topicHandlers: [],
+      configProperties: [],
+      serviceRequests: [],
+      effects: [],
+      futures: []
+    };
+  }
+  const classDecorators = cls.getDecorators().map((d) => d.getName());
+  const kosModelArg = decoratorConfigText(sf, cls, "kosModel");
+  const singleton = /\bsingleton\s*:\s*true\b/.test(kosModelArg ?? "");
+  return {
+    modelFilePath,
+    modelType,
+    className: cls.getName(),
+    classDecorators,
+    singleton,
+    isCompanion: classDecorators.includes("kosCompanion"),
+    children: collectDecorated(cls, "kosChild"),
+    dependencies: collectDecorated(cls, "kosDependency"),
+    topicHandlers: collectDecorated(cls, "kosTopicHandler"),
+    configProperties: collectDecorated(cls, "kosConfigProperty"),
+    serviceRequests: collectDecorated(cls, "kosServiceRequest"),
+    effects: collectDecorated(cls, "kosModelEffect"),
+    futures: collectDecorated(cls, "kosFuture")
+  };
+}
+function addModelEffectToModel(codegenFs, options, projects) {
+  const logger = getCodegenLogger();
+  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
+  if (!codegenFs.exists(modelFilePath)) {
+    throw new Error(`Model file not found: ${modelFilePath}`);
+  }
+  logger.info(
+    `Adding @kosModelEffect "${options.methodName}" to ${options.modelName}`
+  );
+  transformSourceFile(codegenFs, modelFilePath, (sf) => {
+    const sdk = resolveSdkModuleSpecifier(sf);
+    ensureNamedImport(sf, sdk, [{ name: "kosModelEffect" }]);
+    const cls = getModelClass(sf);
+    const modelType = (cls.getName() ?? "").replace(/Impl$/, "");
+    addDecoratedMethod(cls, {
+      name: options.methodName,
+      decoratorName: "kosModelEffect",
+      decoratorArgsText: `{ dependencies: (model: ${modelType}) => [] }`,
+      isAsync: true,
+      returnType: "Promise<void>",
+      statements: "// TODO: react to the tracked dependencies"
+    });
+  });
+  return { modelFilePath };
+}
+const FRAMEWORK_TYPES$1 = /* @__PURE__ */ new Set(["IKosDataModel", "IKosIdentifiable"]);
+function addDependencyToModel(codegenFs, options, projects) {
+  const logger = getCodegenLogger();
+  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
+  if (!codegenFs.exists(modelFilePath)) {
+    throw new Error(`Model file not found: ${modelFilePath}`);
+  }
   logger.info(
     `Adding @kosDependency "${options.propertyName}" to ${options.modelName}`
   );
@@ -2360,7 +2904,18 @@ function addChildToModel(codegenFs, options, projects) {
   logger.info(
     `Adding @kosChild "${options.propertyName}" (${shape}) to ${options.modelName}`
   );
-  const childType = options.childType?.trim();
+  const resolvedChild = options.childModel ? resolveChildModelType(
+    codegenFs,
+    {
+      modelFilePath,
+      modelProject: options.modelProject,
+      childModel: options.childModel,
+      childModelProject: options.childModelProject
+    },
+    projects
+  ) : { childType: options.childType, childTypeModule: options.childPackage };
+  const childType = resolvedChild.childType?.trim();
+  const childTypeModule = resolvedChild.childTypeModule;
   transformSourceFile(codegenFs, modelFilePath, (sf) => {
     const sdk = resolveSdkModuleSpecifier(sf);
     const sdkImports = [
@@ -2368,8 +2923,8 @@ function addChildToModel(codegenFs, options, projects) {
     ];
     if (shape === "container") sdkImports.push({ name: "KosModelContainer" });
     ensureNamedImport(sf, sdk, sdkImports);
-    if (options.childPackage && childType && /^[A-Za-z_$][\w$]*$/.test(childType) && !FRAMEWORK_TYPES.has(childType)) {
-      ensureNamedImport(sf, options.childPackage, [
+    if (childTypeModule && childType && /^[A-Za-z_$][\w$]*$/.test(childType) && !FRAMEWORK_TYPES.has(childType)) {
+      ensureNamedImport(sf, childTypeModule, [
         { name: childType, isTypeOnly: true }
       ]);
     }
@@ -2515,6 +3070,154 @@ function addComputedToModel(codegenFs, options, projects) {
   });
   return { modelFilePath };
 }
+function mocksFilePathFor(modelFilePath, modelBase) {
+  return path.join(
+    path.dirname(modelFilePath),
+    "mocks",
+    `${modelBase}-mocks.ts`
+  );
+}
+function mockRegisterFunctionName(modelBase) {
+  return `register${pascalCase(modelBase)}Mocks`;
+}
+function toMockRoutePattern(servicePath) {
+  return servicePath.replace(/\{([^}]+)\}/g, ":$1");
+}
+function mockRouteCall(method, pattern, body) {
+  const shorthand = {
+    get: "get",
+    post: "post",
+    put: "put",
+    delete: "del"
+  };
+  const fn = shorthand[method];
+  return fn ? `KosMock.${fn}(${JSON.stringify(pattern)}, ${body});` : `KosMock.route(${JSON.stringify(method.toUpperCase())}, ${JSON.stringify(
+    pattern
+  )}, ${body});`;
+}
+function header(modelBase, registerFn) {
+  return `/**
+ * KosMock routes for the ${modelBase} model's PROVISIONAL endpoints — the ones
+ * this project's generated OpenAPI types do not declare.
+ *
+ * NOTHING IMPORTS THIS FILE. Call \`${registerFn}()\` from the app's dev entry,
+ * gated so it cannot run in a production build (\`import.meta.env.DEV\`, a
+ * dev-only entry module, or behind your own switch). Registering a route enables
+ * KosMock, and a mock that shipped would shadow the real endpoint once it exists.
+ *
+ * Unmatched requests still pass through to the real device (KosMock's hybrid
+ * default), so these routes shadow only the paths named below. Every mocked
+ * response carries the \`kos-mocked: true\` wire header, so mock-fed data is
+ * identifiable in devtools.
+ *
+ * DELETE THIS FILE once every endpoint below is in the generated types.
+ */
+`;
+}
+function ensureMockRoute(codegenFs, options) {
+  const mocksFilePath = mocksFilePathFor(
+    options.modelFilePath,
+    options.modelBase
+  );
+  const registerFunction = mockRegisterFunctionName(options.modelBase);
+  const routePattern = toMockRoutePattern(options.servicePath);
+  const sampleName = `SAMPLE_${constantCase(dashCase(options.endpointKey))}`;
+  const samplePlaceholder = !options.sampleText;
+  if (!codegenFs.exists(mocksFilePath)) {
+    codegenFs.write(mocksFilePath, header(options.modelBase, registerFunction));
+  }
+  const sdkSpecifier = options.sdkModuleSpecifier.startsWith(".") ? `../${options.sdkModuleSpecifier}` : options.sdkModuleSpecifier;
+  let routeCreated = false;
+  transformSourceFile(codegenFs, mocksFilePath, (sf) => {
+    ensureNamedImport(sf, sdkSpecifier, [{ name: "KosMock" }]);
+    ensureNamedImport(sf, "../services", [
+      { name: options.rawAlias, isTypeOnly: true }
+    ]);
+    ensureSample(sf, {
+      name: sampleName,
+      type: options.rawAlias,
+      servicePath: options.servicePath,
+      method: options.method,
+      sampleText: options.sampleText
+    });
+    const statement = mockRouteCall(
+      options.method,
+      routePattern,
+      `{ data: ${sampleName} }`
+    );
+    routeCreated = ensureRegisteredRoute(sf, {
+      registerFunction,
+      modelBase: options.modelBase,
+      statement,
+      // Matching on the pattern literal alone would collide across methods.
+      marker: `${options.method.toUpperCase()} ${routePattern}`,
+      matches: (existing) => existing.includes(JSON.stringify(routePattern)) && existing.includes(shorthandOrMethod(options.method))
+    });
+  });
+  return {
+    mocksFilePath,
+    registerFunction,
+    routePattern,
+    sampleName,
+    routeCreated,
+    samplePlaceholder
+  };
+}
+function shorthandOrMethod(method) {
+  const shorthand = {
+    get: "KosMock.get(",
+    post: "KosMock.post(",
+    put: "KosMock.put(",
+    delete: "KosMock.del("
+  };
+  return shorthand[method] ?? `"${method.toUpperCase()}"`;
+}
+function ensureSample(sf, spec) {
+  if (sf.getVariableDeclaration(spec.name)) return;
+  const lines = [
+    `Sample payload for \`${spec.method.toUpperCase()} ${spec.servicePath}\` — the`,
+    "UNWRAPPED `data` payload, i.e. exactly what the transform receives."
+  ];
+  if (!spec.sampleText) {
+    lines.push(
+      "",
+      "TODO: replace the placeholder with something the backend would actually",
+      "serve. Until then the route answers with nothing and the transform is",
+      "never exercised."
+    );
+  }
+  const docs = lines.join("\n");
+  sf.addVariableStatement({
+    isExported: true,
+    declarationKind: VariableDeclarationKind.Const,
+    docs: [docs],
+    declarations: [
+      {
+        name: spec.name,
+        type: spec.type,
+        initializer: spec.sampleText ?? `null as unknown as ${spec.type}`
+      }
+    ]
+  });
+}
+function ensureRegisteredRoute(sf, spec) {
+  let fn = sf.getFunction(spec.registerFunction);
+  if (!fn) {
+    fn = sf.addFunction({
+      name: spec.registerFunction,
+      isExported: true,
+      returnType: "void",
+      docs: [
+        `Arm the ${spec.modelBase} model's provisional endpoints. Call this from a dev-only entry point — never from code that ships.`
+      ]
+    });
+  }
+  const already = fn.getStatements().some((statement) => spec.matches(statement.getText()));
+  if (already) return false;
+  fn.addStatements(`// ${spec.marker}
+${spec.statement}`);
+  return true;
+}
 const SERVICE_MODULE_RE = /\/utils\/services\/.*\/service\.ts$/;
 function findServiceModules(codegenFs, sourceRoot) {
   return codegenFs.listFiles(sourceRoot).filter((f) => SERVICE_MODULE_RE.test(f.split(path.sep).join("/")));
@@ -2539,10 +3242,30 @@ function assertServiceModuleAcceptsTransform(codegenFs, serviceModuleFile, model
     `${file} predates the transform-aware service layer (EndpointCtx takes ${typeParams} type parameter). Run \`kosui api:generate --project ${modelProject} --helpers-only\` to refresh the helper layer in place (no spec fetch, openapi.d.ts untouched), then add the service request.`
   );
 }
+const MUTATING_METHODS = /* @__PURE__ */ new Set(["post", "put", "delete", "patch"]);
+function assertLifecycleSuitsMethod(method, mode, methodName) {
+  if (mode !== "lifecycle" || !MUTATING_METHODS.has(method)) return;
+  throw new Error(
+    `${methodName} is a ${method.toUpperCase()} with a lifecycle, so it would run every time the model reaches that phase rather than when something calls it — a mutation on every load. Drop \`lifecycle\` to get the method-driven form (the default for ${method.toUpperCase()}), or pass \`mode: "method"\`. If the phase really is the trigger, the model calls the method from its own lifecycle hook, where the call is visible.`
+  );
+}
+function assertServiceModuleAcceptsProvisional(codegenFs, serviceModuleFile, modelProject) {
+  const file = `${serviceModuleFile}.ts`;
+  if (!codegenFs.exists(file)) return;
+  const declared = readSourceFile(
+    codegenFs,
+    file,
+    (sf) => Boolean(sf.getFunction("provisionalServiceRequest"))
+  );
+  if (declared) return;
+  throw new Error(
+    `${file} has no \`provisionalServiceRequest\` — the helper layer predates provisional endpoints. Run \`kosui api:generate --project ${modelProject} --helpers-only\` to refresh it in place (no spec fetch, openapi.d.ts untouched), then add the service request.`
+  );
+}
 function sameEndpoint(existing, candidate) {
   const args = (text) => {
     const match = text.match(
-      /^endpoint\s*\(\s*(['"])(.*?)\1\s*,\s*(['"])(.*?)\3\s*,?\s*\)$/
+      /^endpoint\s*\(\s*(['"])(.*?)\1(?:\s+as\s+ApiPath)?\s*,\s*(['"])(.*?)\3\s*,?\s*\)$/
     );
     return match ? [match[2], match[4].toLowerCase()] : null;
   };
@@ -2550,6 +3273,104 @@ function sameEndpoint(existing, candidate) {
   const b = args(candidate.trim());
   return !!a && !!b && a[0] === b[0] && a[1] === b[1];
 }
+function editDistance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      current[j] = Math.min(
+        previous[j] + 1,
+        current[j - 1] + 1,
+        previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+    }
+    previous = current;
+  }
+  return previous[b.length];
+}
+const NEAREST_SHOWN = 5;
+function provisionalEntryComment(servicePath, method, catalogName) {
+  return `/**
+ * PROVISIONAL — \`${method.toUpperCase()} ${servicePath}\` is NOT in this project's
+ * generated OpenAPI types. \`as ApiPath\` is standing in for a \`paths\` entry that
+ * does not exist, so nothing about this endpoint is checked against a spec and
+ * its response cannot be derived from one. Do not read this as a real endpoint.
+ *
+ * WHEN THE ENDPOINT LANDS:
+ *   1. regenerate this project's API types (\`kosui api:generate\`)
+ *   2. delete \` as ApiPath\` from the entry below
+ *   3. point the endpoint's \`…Raw\` alias at
+ *      \`EndpointResponse<typeof ${catalogName}.…>\`
+ *   4. swap \`provisionalServiceRequest\` for \`serviceRequest\` in the model
+ *   5. delete the model's \`mocks/\` module
+ *   6. KEEP the transform — it is real code and survives all of the above
+ */
+`;
+}
+function provisionalMethodDocs(servicePath, method) {
+  return [
+    `PROVISIONAL — \`${method.toUpperCase()} ${servicePath}\` is not in the`,
+    "generated OpenAPI types, so this request is served by a KosMock route, not",
+    "by the device. The feature it backs is NOT complete: report the missing",
+    "endpoint rather than treating this as finished.",
+    "",
+    "See the endpoint's entry in `./services` for what to undo when it lands."
+  ].join("\n");
+}
+function rawTypeDocs(servicePath, method, rawType) {
+  const shape = rawType ? [
+    "Stated by hand and unverified: there is no spec entry to check it",
+    "against."
+  ] : [
+    "TODO: state the shape the backend is expected to serve. `unknown`",
+    "compiles, but leaves the response boundary undescribed and the",
+    "transform with nothing to narrow."
+  ];
+  return [
+    `Raw wire shape of \`${method.toUpperCase()} ${servicePath}\` — the UNWRAPPED`,
+    "`data` payload, since the client strips the `{status, data}` envelope",
+    "before the transform runs.",
+    "",
+    ...shape,
+    "",
+    "Replace with `EndpointResponse<…>` once the endpoint is in the generated",
+    "types."
+  ].join("\n");
+}
+function removalSteps(spec) {
+  return [
+    `Regenerate the API types for ${spec.modelProject} (generate_api_types), and confirm ${spec.method.toUpperCase()} ${spec.servicePath} is now in them.`,
+    `In ${spec.servicesFilePath}: delete \` as ApiPath\` from \`${spec.catalogName}.${spec.endpointKey}\`.`,
+    `In ${spec.servicesFilePath}: point the endpoint's \`…Raw\` alias at \`EndpointResponse<typeof ${spec.catalogName}.${spec.endpointKey}>\` and drop the hand-written shape.`,
+    `In the model: swap \`provisionalServiceRequest\` for \`serviceRequest\` and drop its explicit type arguments — the response type comes from the spec again.`,
+    spec.mocksFilePath ? `Delete ${spec.mocksFilePath} (and the call to its register function in the app) once no provisional endpoint is left in it.` : `Delete the model's mocks module once no provisional endpoint is left in it.`,
+    `KEEP \`${spec.mapperName}\` and the data type it produces. The transform is real code; it is what let the model read the final shape all along.`
+  ];
+}
+function untypedEndpointError(spec) {
+  const methodsForPath = spec.operations.filter((op) => op.path === spec.servicePath).map((op) => op.method);
+  const pathTypedForOtherMethods = methodsForPath.length > 0;
+  const nearest = [...new Set(spec.operations.map((op) => op.path))].sort(
+    (a, b) => editDistance(a, spec.servicePath) - editDistance(b, spec.servicePath)
+  ).slice(0, NEAREST_SHOWN);
+  const waysForward = [
+    `The endpoint EXISTS on the device but this project has not pulled types for it: re-run api:generate (generate_api_types) for ${spec.modelProject}, then add the request unchanged. Confirm on the device first — kos-device search_services / describe_endpoint — since the live OpenAPI is what says whether it exists.`,
+    `The endpoint DOES NOT EXIST yet: pass mock:"auto" (the default) or mock:"always" to emit the provisional, mock-backed form — real decorator, lifecycle, error-first handler and transform, with a KosMock route standing in for the wire response.`,
+    `What is NOT supported: falling back to resolveServiceUrl / ServiceFactory.build / getAll to make the UI render. That compiles and looks finished, which is worse than the hole. A missing endpoint is a blocker to report, not a licence to route around the generated service layer.`
+  ];
+  const message = pathTypedForOtherMethods ? `${spec.method.toUpperCase()} ${spec.servicePath} is not in the generated OpenAPI types for ${spec.modelProject} — the path is typed, but only for: ${methodsForPath.map((m) => m.toUpperCase()).join(", ")}.` : `${spec.method.toUpperCase()} ${spec.servicePath} is not in the generated OpenAPI types for ${spec.modelProject} — the path is absent entirely. Nothing was written.`;
+  const error = new Error(message);
+  error.details = {
+    servicePath: spec.servicePath,
+    method: spec.method,
+    pathTypedForOtherMethods,
+    methodsForPath,
+    otherEndpointsInThisApi: nearest,
+    warning: "These are OTHER endpoints in this API, listed only so they can be ruled out — they are almost certainly NOT what you want. Do not substitute one for the requested path because the strings look similar.",
+    waysForward
+  };
+  return error;
+}
 function addServiceRequestToModel(codegenFs, options, projects) {
   const logger = getCodegenLogger();
   const { modelFilePath, sourceRoot } = resolveModelFilePath(
@@ -2609,36 +3430,89 @@ function addServiceRequestToModel(codegenFs, options, projects) {
   );
   const method = (options.method || "get").toLowerCase();
   const mode = options.mode ?? (options.lifecycle ? "lifecycle" : "method");
+  assertLifecycleSuitsMethod(method, mode, options.methodName);
   const lifecycle = options.lifecycle || "LOAD";
   const catalogName = `${pascalCase(modelBase)}Endpoints`;
+  const mockMode = options.mock ?? "auto";
+  const operations = readServiceModuleOperations(codegenFs, serviceModuleFile);
+  const pathValidated = operations !== null;
+  const operationTyped = operations === null || operations.some(
+    (op) => op.path === options.servicePath && op.method === method
+  );
+  if (!operationTyped && mockMode === "never") {
+    throw untypedEndpointError({
+      servicePath: options.servicePath,
+      method,
+      modelProject: options.modelProject,
+      operations: operations ?? []
+    });
+  }
+  const provisional = !operationTyped;
+  const writeMock = provisional || mockMode === "always";
+  if (provisional) {
+    assertServiceModuleAcceptsProvisional(
+      codegenFs,
+      serviceModuleFile,
+      options.modelProject
+    );
+  }
   logger.info(
-    `Adding ${mode}-driven @kosServiceRequest "${options.methodName}" (${method} ${options.servicePath}) to ${options.modelName}`
+    `Adding ${mode}-driven ${provisional ? "PROVISIONAL " : ""}@kosServiceRequest "${options.methodName}" (${method} ${options.servicePath}) to ${options.modelName}`
   );
+  if (provisional) {
+    logger.warn(
+      `${method.toUpperCase()} ${options.servicePath} is not in ${options.modelProject}'s generated OpenAPI types — emitting the provisional, mock-backed form. The feature is NOT complete until the endpoint lands.`
+    );
+  }
   ensureServicesModule(codegenFs, modelFilePath, modelBase);
   let endpointKey = options.methodName;
   let endpointCreated = true;
   let dataAlias = "";
   let mapperName = "";
   let ctxAlias = "";
+  let rawAlias = "";
   transformSourceFile(codegenFs, servicesFilePath, (sf) => {
     ensureNamedImport(sf, serviceImportFromServices, [{ name: "endpoint" }]);
+    if (provisional) {
+      ensureNamedImport(sf, serviceImportFromServices, [
+        { name: "ApiPath", isTypeOnly: true }
+      ]);
+    }
+    const pathText = provisional ? `${JSON.stringify(options.servicePath)} as ApiPath` : JSON.stringify(options.servicePath);
     const entry = ensureConstCatalogEntry(sf, {
       catalogName,
       key: options.methodName,
-      initializer: `endpoint(${JSON.stringify(
-        options.servicePath
-      )}, ${JSON.stringify(method)})`,
-      equals: sameEndpoint
+      initializer: `endpoint(${pathText}, ${JSON.stringify(method)})`,
+      equals: sameEndpoint,
+      leadingTrivia: provisional ? provisionalEntryComment(options.servicePath, method, catalogName) : void 0
     });
     endpointKey = entry.key;
     endpointCreated = entry.created;
     dataAlias = `${pascalCase(endpointKey)}Data`;
     mapperName = `to${pascalCase(endpointKey)}Data`;
     ctxAlias = `${pascalCase(endpointKey)}Ctx`;
-    const rawType = `EndpointResponse<typeof ${catalogName}.${endpointKey}>`;
-    ensureNamedImport(sf, serviceImportFromServices, [
-      { name: "EndpointResponse", isTypeOnly: true }
-    ]);
+    rawAlias = `${pascalCase(endpointKey)}Raw`;
+    let rawType;
+    if (provisional) {
+      ensureExportedTypeAlias(sf, {
+        name: rawAlias,
+        type: options.rawType || "unknown",
+        docs: rawTypeDocs(options.servicePath, method, options.rawType)
+      });
+      rawType = rawAlias;
+    } else {
+      rawType = `EndpointResponse<typeof ${catalogName}.${endpointKey}>`;
+      ensureNamedImport(sf, serviceImportFromServices, [
+        { name: "EndpointResponse", isTypeOnly: true }
+      ]);
+      if (writeMock) {
+        ensureExportedTypeAlias(sf, {
+          name: rawAlias,
+          type: rawType,
+          docs: `Raw wire shape of \`${method.toUpperCase()} ${options.servicePath}\`, as the spec declares it — what a mock for this endpoint must serve.`
+        });
+      }
+    }
     ensureExportedTypeAlias(sf, { name: dataAlias, type: rawType });
     ensureExportedMapper(sf, {
       name: mapperName,
@@ -2659,20 +3533,25 @@ function addServiceRequestToModel(codegenFs, options, projects) {
     const className = getModelClass(sf).getName();
     if (!className) throw new Error("Model class has no name.");
     const typeParams = getModelClass(sf).getTypeParameters().map((tp) => tp.getText());
-    ensureNamedImport(sf, serviceImportFromModel, [{ name: "serviceRequest" }]);
+    const decoratorName = provisional ? "provisionalServiceRequest" : "serviceRequest";
+    const decoratorTypeArgs = provisional ? [rawAlias, dataAlias] : void 0;
+    ensureNamedImport(sf, serviceImportFromModel, [{ name: decoratorName }]);
     if (mode === "lifecycle") {
       ensureNamedImport(sf, "./services", [
         { name: catalogName },
         { name: mapperName },
-        { name: dataAlias, isTypeOnly: true }
+        { name: dataAlias, isTypeOnly: true },
+        ...provisional ? [{ name: rawAlias, isTypeOnly: true }] : []
       ]);
       ensureNamedImport(sf, resolveSdkModuleSpecifier(sf), [
         { name: "DependencyLifecycle" }
       ]);
       addDecoratedMethod(getModelClass(sf), {
         name: options.methodName,
-        decoratorName: "serviceRequest",
+        decoratorName,
+        decoratorTypeArgs,
         decoratorArgsText: `${catalogName}.${endpointKey}, { lifecycle: DependencyLifecycle.${lifecycle}, transform: ${mapperName} }`,
+        docs: provisional ? provisionalMethodDocs(options.servicePath, method) : void 0,
         // The manager invokes phase handlers error-first, passing (null, data)
         // on success. The `error` half is only ever reached because
         // `serviceRequest` supplies an errorHandler — the bare decorator
@@ -2689,7 +3568,11 @@ function addServiceRequestToModel(codegenFs, options, projects) {
     ensureNamedImport(sf, "./services", [
       { name: catalogName },
       { name: mapperName },
-      { name: ctxAlias, isTypeOnly: true }
+      { name: ctxAlias, isTypeOnly: true },
+      ...provisional ? [
+        { name: rawAlias, isTypeOnly: true },
+        { name: dataAlias, isTypeOnly: true }
+      ] : []
     ]);
     ensureNamedImport(sf, resolveSdkModuleSpecifier(sf), [
       { name: "executeServiceRequest" },
@@ -2704,8 +3587,10 @@ function addServiceRequestToModel(codegenFs, options, projects) {
     addClassDecorator(getModelClass(sf), "kosLoggerAware", { argsText: "" });
     addDecoratedMethod(getModelClass(sf), {
       name: options.methodName,
-      decoratorName: "serviceRequest",
+      decoratorName,
+      decoratorTypeArgs,
       decoratorArgsText: `${catalogName}.${endpointKey}, { transform: ${mapperName} }`,
+      docs: provisional ? provisionalMethodDocs(options.servicePath, method) : void 0,
       // Optional: the framework appends the context, callers never pass it.
       parameters: [{ name: "$ctx", type: ctxAlias, optional: true }],
       isAsync: true,
@@ -2717,172 +3602,43 @@ function addServiceRequestToModel(codegenFs, options, projects) {
       ].join("\n")
     });
   });
+  const mock = writeMock ? ensureMockRoute(codegenFs, {
+    modelFilePath,
+    modelBase,
+    sdkModuleSpecifier: readSourceFile(
+      codegenFs,
+      modelFilePath,
+      resolveSdkModuleSpecifier
+    ),
+    rawAlias,
+    servicePath: options.servicePath,
+    method,
+    endpointKey,
+    sampleText: options.sample
+  }) : void 0;
   return {
     modelFilePath,
     servicesFilePath,
     serviceModule: serviceImportFromModel,
     mode,
     endpointKey,
-    endpointCreated
-  };
-}
-function modelElementType(typeText) {
-  let m;
-  if (m = typeText.match(/^([A-Za-z_]\w*Model)\s*\[\]$/)) return m[1];
-  if (m = typeText.match(/^Array<\s*([A-Za-z_]\w*Model)\s*>$/)) return m[1];
-  if (m = typeText.match(/^(?:Map|Set)<[^>]*?\b([A-Za-z_]\w*Model)\b[^>]*>$/))
-    return m[1];
-  return null;
-}
-function validateModel(codegenFs, options, projects) {
-  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
-  const content = codegenFs.read(modelFilePath);
-  if (content === null) {
-    throw new Error(`Model file not found: ${modelFilePath}`);
-  }
-  const project = new Project({ useInMemoryFileSystem: true });
-  const sf = project.createSourceFile(modelFilePath, content, {
-    overwrite: true
-  });
-  const findings = [];
-  const hasKosModel = sf.getClasses().some((c) => c.getDecorator("kosModel"));
-  if (!hasKosModel) {
-    findings.push({
-      level: "error",
-      rule: "missing-kosModel",
-      message: "No @kosModel decorator found — this is not a KOS model."
-    });
-  }
-  const imports = sf.getImportDeclarations();
-  const mobxImport = imports.find(
-    (d) => /^mobx(-react-lite)?$/.test(d.getModuleSpecifierValue())
-  );
-  if (mobxImport) {
-    findings.push({
-      level: "error",
-      rule: "mobx-import",
-      message: "Imports mobx directly. Reactivity is internal to KOS — remove the mobx import and use KOS reactivity / container models."
-    });
-  }
-  const barrelServiceRequest = imports.find(
-    (d) => d.getModuleSpecifierValue() === "@kosdev-code/kos-ui-sdk" && d.getNamedImports().some((n) => n.getName() === "kosServiceRequest")
-  );
-  if (barrelServiceRequest) {
-    findings.push({
-      level: "warning",
-      rule: "untyped-service-request",
-      message: "kosServiceRequest imported from the SDK barrel. Use the typed decorator from the api:generate'd service module so paths are validated against the OpenAPI types."
-    });
-  }
-  for (const cls of sf.getClasses()) {
-    for (const prop of cls.getProperties()) {
-      const name = prop.getName();
-      const typeText = (prop.getTypeNode()?.getText() ?? "").replace(/\s+/g, " ").trim();
-      const initText = prop.getInitializer()?.getText() ?? "";
-      const hasChild = !!prop.getDecorator("kosChild");
-      const isModelContainer = /\bI?KosModelContainer\s*</.test(typeText) || /new\s+KosModelContainer\b/.test(initText);
-      if (isModelContainer && !hasChild) {
-        findings.push({
-          level: "warning",
-          rule: "container-missing-kosChild",
-          message: `Property '${name}' is a model container but is not marked @kosChild — add @kosChild so its models join the model graph and lifecycle.`
-        });
-        continue;
-      }
-      const elem = modelElementType(typeText);
-      if (elem && !isModelContainer) {
-        findings.push({
-          level: "warning",
-          rule: "raw-model-collection",
-          message: `Property '${name}' is a raw ${typeText} of models — prefer a KosModelContainer<${elem}> (indexing, sorting, lifecycle, delta handling) marked @kosChild.`
-        });
-      }
-    }
-  }
-  const hasError = findings.some((f) => f.level === "error");
-  return { modelFilePath, ok: !hasError, findings };
-}
-function firstDecoratorArg(decoratorText) {
-  const open = decoratorText.indexOf("(");
-  if (open === -1) return void 0;
-  const inner = decoratorText.slice(open + 1, decoratorText.lastIndexOf(")")).replace(/\s+/g, " ").trim();
-  return inner || void 0;
-}
-function collectDecorated(cls, decoratorName) {
-  const members = [];
-  const visit = (name, decoratorTextOf, typeText) => {
-    const text = decoratorTextOf();
-    if (text === void 0) return;
-    members.push({
-      name,
-      arg: firstDecoratorArg(text),
-      type: typeText || void 0
-    });
-  };
-  for (const m of cls.getMethods()) {
-    const dec = m.getDecorator(decoratorName);
-    if (dec) {
-      visit(m.getName(), () => dec.getText(), m.getReturnTypeNode()?.getText());
-    }
-  }
-  for (const p of cls.getProperties()) {
-    const dec = p.getDecorator(decoratorName);
-    if (dec) {
-      visit(p.getName(), () => dec.getText(), p.getTypeNode()?.getText());
-    }
-  }
-  return members;
-}
-function describeModel(codegenFs, options, projects) {
-  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
-  const content = codegenFs.read(modelFilePath);
-  if (content === null) {
-    throw new Error(`Model file not found: ${modelFilePath}`);
-  }
-  const project = new Project({ useInMemoryFileSystem: true });
-  const sf = project.createSourceFile(modelFilePath, content, {
-    overwrite: true
-  });
-  let modelType;
-  const modelTypeDecl = sf.getVariableDeclaration("MODEL_TYPE");
-  if (modelTypeDecl) {
-    const init = modelTypeDecl.getInitializer()?.getText();
-    if (init) modelType = init.replace(/^["'`]|["'`]$/g, "");
-  }
-  const cls = sf.getClasses().find((c) => c.getDecorator("kosModel")) ?? sf.getClasses().find((c) => c.isExported()) ?? sf.getClasses()[0];
-  if (!cls) {
-    return {
-      modelFilePath,
-      modelType,
-      classDecorators: [],
-      singleton: false,
-      isCompanion: false,
-      children: [],
-      dependencies: [],
-      topicHandlers: [],
-      configProperties: [],
-      serviceRequests: [],
-      effects: [],
-      futures: []
-    };
-  }
-  const classDecorators = cls.getDecorators().map((d) => d.getName());
-  const kosModelArg = cls.getDecorator("kosModel") ? firstDecoratorArg(cls.getDecorator("kosModel").getText()) : void 0;
-  const singleton = /\bsingleton\s*:\s*true\b/.test(kosModelArg ?? "");
-  return {
-    modelFilePath,
-    modelType,
-    className: cls.getName(),
-    classDecorators,
-    singleton,
-    isCompanion: classDecorators.includes("kosCompanion"),
-    children: collectDecorated(cls, "kosChild"),
-    dependencies: collectDecorated(cls, "kosDependency"),
-    topicHandlers: collectDecorated(cls, "kosTopicHandler"),
-    configProperties: collectDecorated(cls, "kosConfigProperty"),
-    serviceRequests: collectDecorated(cls, "kosServiceRequest"),
-    effects: collectDecorated(cls, "kosModelEffect"),
-    futures: collectDecorated(cls, "kosFuture")
+    endpointCreated,
+    pathValidated,
+    provisional,
+    mocksFilePath: mock?.mocksFilePath,
+    mockRegisterFunction: mock?.registerFunction,
+    mockRoute: mock && `${method.toUpperCase()} ${mock.routePattern}`,
+    mockSamplePlaceholder: mock?.samplePlaceholder,
+    removalSteps: provisional ? removalSteps({
+      modelProject: options.modelProject,
+      servicePath: options.servicePath,
+      method,
+      catalogName,
+      endpointKey,
+      servicesFilePath,
+      mocksFilePath: mock?.mocksFilePath,
+      mapperName
+    }) : void 0
   };
 }
 const DEFAULT_SDK_PACKAGE = "@kosdev-code/kos-ui-sdk";
@@ -3068,6 +3824,82 @@ function lookupSdkType(codegenFs, options, projects) {
     )}). Check the name, or it may be internal / not part of the public surface.`
   };
 }
+function modelElementType(typeText) {
+  let m;
+  if (m = typeText.match(/^([A-Za-z_]\w*Model)\s*\[\]$/)) return m[1];
+  if (m = typeText.match(/^Array<\s*([A-Za-z_]\w*Model)\s*>$/)) return m[1];
+  if (m = typeText.match(/^(?:Map|Set)<[^>]*?\b([A-Za-z_]\w*Model)\b[^>]*>$/))
+    return m[1];
+  return null;
+}
+function validateModel(codegenFs, options, projects) {
+  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
+  const content = codegenFs.read(modelFilePath);
+  if (content === null) {
+    throw new Error(`Model file not found: ${modelFilePath}`);
+  }
+  const project = new Project({ useInMemoryFileSystem: true });
+  const sf = project.createSourceFile(modelFilePath, content, {
+    overwrite: true
+  });
+  const findings = [];
+  const hasKosModel = sf.getClasses().some((c) => c.getDecorator("kosModel"));
+  if (!hasKosModel) {
+    findings.push({
+      level: "error",
+      rule: "missing-kosModel",
+      message: "No @kosModel decorator found — this is not a KOS model."
+    });
+  }
+  const imports = sf.getImportDeclarations();
+  const mobxImport = imports.find(
+    (d) => /^mobx(-react-lite)?$/.test(d.getModuleSpecifierValue())
+  );
+  if (mobxImport) {
+    findings.push({
+      level: "error",
+      rule: "mobx-import",
+      message: "Imports mobx directly. Reactivity is internal to KOS — remove the mobx import and use KOS reactivity / container models."
+    });
+  }
+  const barrelServiceRequest = imports.find(
+    (d) => d.getModuleSpecifierValue() === "@kosdev-code/kos-ui-sdk" && d.getNamedImports().some((n) => n.getName() === "kosServiceRequest")
+  );
+  if (barrelServiceRequest) {
+    findings.push({
+      level: "warning",
+      rule: "untyped-service-request",
+      message: "kosServiceRequest imported from the SDK barrel. Use the typed decorator from the api:generate'd service module so paths are validated against the OpenAPI types."
+    });
+  }
+  for (const cls of sf.getClasses()) {
+    for (const prop of cls.getProperties()) {
+      const name = prop.getName();
+      const typeText = (prop.getTypeNode()?.getText() ?? "").replace(/\s+/g, " ").trim();
+      const initText = prop.getInitializer()?.getText() ?? "";
+      const hasChild = !!prop.getDecorator("kosChild");
+      const isModelContainer = /\bI?KosModelContainer\s*</.test(typeText) || /new\s+KosModelContainer\b/.test(initText);
+      if (isModelContainer && !hasChild) {
+        findings.push({
+          level: "warning",
+          rule: "container-missing-kosChild",
+          message: `Property '${name}' is a model container but is not marked @kosChild — add @kosChild so its models join the model graph and lifecycle.`
+        });
+        continue;
+      }
+      const elem = modelElementType(typeText);
+      if (elem && !isModelContainer) {
+        findings.push({
+          level: "warning",
+          rule: "raw-model-collection",
+          message: `Property '${name}' is a raw ${typeText} of models — prefer a KosModelContainer<${elem}> (indexing, sorting, lifecycle, delta handling) marked @kosChild.`
+        });
+      }
+    }
+  }
+  const hasError = findings.some((f) => f.level === "error");
+  return { modelFilePath, ok: !hasError, findings };
+}
 const PLUGIN_TYPES = {
   CUI: "cui",
   UTILITY: "utility",
@@ -3622,9 +4454,76 @@ function updatePluginConfiguration(codegenFs, projectConfig, options) {
     );
   }
 }
+function parse(content) {
+  const singleQuoted = /^\s*import\b[^"']*'/m.test(content);
+  const project = new Project({
+    useInMemoryFileSystem: true,
+    manipulationSettings: {
+      indentationText: IndentationText.TwoSpaces,
+      quoteKind: singleQuoted ? QuoteKind.Single : QuoteKind.Double
+    }
+  });
+  return project.createSourceFile("registration-chain.ts", content, {
+    overwrite: true
+  });
+}
+function chainCalls(sf, name) {
+  return sf.getDescendantsOfKind(SyntaxKind.CallExpression).filter((call) => {
+    const callee = call.getExpression();
+    return callee.getKind() === SyntaxKind.PropertyAccessExpression && callee.asKindOrThrow(SyntaxKind.PropertyAccessExpression).getName() === name;
+  });
+}
+function indentOfCall(sf, call) {
+  const text = sf.getFullText();
+  const nameNode = call.getExpression().asKindOrThrow(SyntaxKind.PropertyAccessExpression).getNameNode();
+  const lineStart = text.lastIndexOf("\n", nameNode.getStart()) + 1;
+  return text.slice(lineStart).match(/^[ \t]*/)?.[0] ?? "";
+}
+function countChainEntries(content) {
+  return chainCalls(parse(content), "model").length;
+}
+function upsertChainEntry(content, bean, importSpec) {
+  const sf = parse(content);
+  const modelCalls = chainCalls(sf, "model");
+  const registered = modelCalls.some((call) => {
+    const [arg, ...rest] = call.getArguments();
+    return rest.length === 0 && arg?.getText() === bean;
+  });
+  if (registered) return { changed: false, note: "already registered" };
+  let anchor;
+  let indent;
+  if (modelCalls.length > 0) {
+    anchor = modelCalls.reduce(
+      (last, call) => call.getEnd() > last.getEnd() ? call : last
+    );
+    indent = indentOfCall(sf, anchor);
+  } else {
+    const starts = chainCalls(sf, "models").filter(
+      (call) => call.getArguments().length === 0
+    );
+    anchor = starts[starts.length - 1];
+    if (!anchor) {
+      return {
+        changed: false,
+        error: "no .models() chain found in the registration file"
+      };
+    }
+    const text = sf.getFullText();
+    const lineStart = text.lastIndexOf("\n", anchor.getStart()) + 1;
+    indent = (text.slice(lineStart).match(/^[ \t]*/)?.[0] ?? "") + "  ";
+  }
+  anchor.replaceWithText(`${anchor.getText()}
+${indent}.model(${bean})`);
+  const imported = sf.getImportDeclarations().some(
+    (decl) => decl.getNamedImports().some((named) => named.getName() === bean)
+  );
+  if (!imported) ensureNamedImport(sf, importSpec, [{ name: bean }]);
+  return { changed: true, content: sf.getFullText(), importAdded: !imported };
+}
 export {
   BasePluginHandler,
   CONTRIBUTION_TYPE_MAP,
+  DEFAULT_MODEL_LIBS_DIR,
   DirectFileSystem,
   KAB_OUTPUT_DIR,
   KAB_OUTPUT_PATH,
@@ -3646,6 +4545,7 @@ export {
   addJavaArtifactToManifests,
   addKosModelConfiguration,
   addModelEffectToModel,
+  addParentAwareToModel,
   addPropertyToModel,
   addServiceRequestToModel,
   addTopicHandlerToModel,
@@ -3654,6 +4554,7 @@ export {
   buildSbomTarget,
   camelCase,
   constantCase,
+  countChainEntries,
   dashCase,
   describeModel,
   discoverJavaArtifacts,
@@ -3672,8 +4573,10 @@ export {
   generateHook,
   generateInit,
   generateModel,
+  generateModelProject,
   generatePolyglotWorkspace,
   generateSplashProject,
+  generateViewModel,
   getCodegenLogger,
   getCurrentDirectoryName,
   getKosModelConfigProp,
@@ -3691,10 +4594,12 @@ export {
   readNxJson,
   resolveKabPath,
   resolveModelFilePath,
+  resolveModelProjectLayout,
   setCodegenLogger,
   syncCiManifests,
   updateJson,
   updateModelIndex,
+  upsertChainEntry,
   validateModel,
   writeJson
 };