@kosdev-code/kos-codegen-core 0.1.0-next.862 → 0.1.0-next.865

package/index.d.ts

@@ -13,5 +13,5 @@ export { getCurrentDirectoryName, getProject, getKosProjectConfiguration, getKos
 export type { KosModelConfiguration, KosProjectConfiguration, } from './lib/kos-config';
 export { getTemplateDir } from './lib/template-resolver';
 export { generateSplashProject, generateInit, generatePolyglotWorkspace, ensureJavaAggregatorPom, finalizeArchetypeModule, addJavaArtifactToManifests, syncCiManifests, discoverUiArtifacts, discoverJavaArtifacts, buildKabTargets, buildSbomTarget, listServiceCatalog, resolveKabPath, KAB_OUTPUT_DIR, KAB_OUTPUT_PATH, UPDATE_RELEASE_VERSION_SCRIPT, UPDATE_RELEASE_VERSION_SCRIPT_PATH, normalizeOptions, appendBarrelExport, updateModelIndex, generateHook, generateContext, generateContainerModel, generateCompanionModel, generateModel, addFutureToModel, addContainerSupportToModel, addModelEffectToModel, addDependencyToModel, addChildToModel, addTopicHandlerToModel, addConfigPropertyToModel, addServiceRequestToModel, addPropertyToModel, addComputedToModel, validateModel, describeModel, lookupSdkType, resolveModelFilePath, generateComponent, PLUGIN_TYPES, CONTRIBUTION_TYPE_MAP, LOCALIZED_PLUGIN_TYPES, KOS_JSON_PATHS, PluginHandlerFactory, BasePluginHandler, KosConfigBuilder, ValidationError, } from './lib/generators';
-export type { SplashProjectOptions, KosInitOptions, KabTargetsOptions, KabTargetDefinition, PolyglotWorkspaceOptions, PolyglotWorkspaceResult, EnsureJavaAggregatorOptions, FinalizeArchetypeModuleOptions, AddJavaArtifactOptions, CiSyncOptions, CiSyncResult, CiSyncManifestResult, DiscoveredArtifact, KosBaseGeneratorOptions, NormalizedOptions, HookOptions, ContextOptions, ContainerModelOptions, CompanionModelOptions, ModelOptions, GenerateModelParams, AddFutureToModelOptions, NormalizedAddFutureToModelOptions, AddContainerSupportOptions, AddModelEffectOptions, AddDependencyOptions, AddChildOptions, ChildShape, AddTopicHandlerOptions, AddConfigPropertyOptions, AddServiceRequestOptions, AddPropertyOptions, AddComputedOptions, ValidateModelOptions, ValidationFinding, ValidationResult, DescribeModelOptions, DescribedMember, ModelDescription, ModelFileQuery, LookupSdkTypeOptions, SdkSymbolDeclaration, SdkTypeLookupResult, ComponentOptions, NormalizedComponentOptions, PluginConfiguration, PluginContribution, ExperienceConfig, PluginType, PluginHandler, } from './lib/generators';
+export type { SplashProjectOptions, KosInitOptions, KabTargetsOptions, KabTargetDefinition, PolyglotWorkspaceOptions, PolyglotWorkspaceResult, EnsureJavaAggregatorOptions, FinalizeArchetypeModuleOptions, AddJavaArtifactOptions, CiSyncOptions, CiSyncResult, CiSyncManifestResult, DiscoveredArtifact, KosBaseGeneratorOptions, NormalizedOptions, HookOptions, ContextOptions, ContainerModelOptions, CompanionModelOptions, ModelOptions, GenerateModelParams, AddFutureToModelOptions, NormalizedAddFutureToModelOptions, AddContainerSupportOptions, AddModelEffectOptions, AddDependencyOptions, AddChildOptions, ChildShape, AddTopicHandlerOptions, AddConfigPropertyOptions, AddServiceRequestOptions, AddServiceRequestResult, ServiceRequestMockMode, UntypedEndpointDetails, UntypedEndpointError, AddPropertyOptions, AddComputedOptions, ValidateModelOptions, ValidationFinding, ValidationResult, DescribeModelOptions, DescribedMember, ModelDescription, ModelFileQuery, LookupSdkTypeOptions, SdkSymbolDeclaration, SdkTypeLookupResult, ComponentOptions, NormalizedComponentOptions, PluginConfiguration, PluginContribution, ExperienceConfig, PluginType, PluginHandler, } from './lib/generators';
 //# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../packages/kos-codegen-core/src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../packages/kos-codegen-core/src/index.ts"],"names":[],"mappings":"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"}

package/index.js

@@ -1088,7 +1088,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 };
   }
@@ -1106,7 +1107,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 };
 }
@@ -1115,7 +1117,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;
 }
@@ -1145,6 +1148,7 @@ function addDecoratedMethod(cls, spec) {
     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 };
     }),
@@ -1152,6 +1156,7 @@ function addDecoratedMethod(cls, spec) {
     decorators: [
       {
         name: spec.decoratorName,
+        typeArguments: spec.decoratorTypeArgs,
         arguments: spec.decoratorArgsText ? [spec.decoratorArgsText] : []
       }
     ]
@@ -1234,17 +1239,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__namespace.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());
@@ -1766,7 +1782,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
@@ -1777,7 +1793,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__namespace.join(path__namespace.dirname(servicesFilePath), "index.ts");
   if (!codegenFs.exists(barrelPath)) {
@@ -2537,6 +2553,154 @@ function addComputedToModel(codegenFs, options, projects) {
   });
   return { modelFilePath };
 }
+function mocksFilePathFor(modelFilePath, modelBase) {
+  return path__namespace.join(
+    path__namespace.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: tsMorph.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__namespace.sep).join("/")));
@@ -2561,10 +2725,23 @@ 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.`
   );
 }
+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;
   };
@@ -2572,6 +2749,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(
@@ -2633,34 +2908,86 @@ function addServiceRequestToModel(codegenFs, options, projects) {
   const mode = options.mode ?? (options.lifecycle ? "lifecycle" : "method");
   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,
@@ -2681,20 +3008,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
@@ -2711,7 +3043,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" },
@@ -2726,8 +3062,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,
@@ -2739,13 +3077,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
+    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
   };
 }
 function modelElementType(typeText) {