feat: complete contract-driven business development and MySQL integration

2026-09-24 21:56:04 +08:00
parent f9afb8f8dd
commit f5478cdc76
108 changed files with 6557 additions and 550 deletions
--- a/cmd/go-omni/README.md
+++ b/cmd/go-omni/README.md
@@ -1,12 +1,14 @@
 # go-omni CLI

+v0.14 新增 `api format [--check]`、`api upgrade [--dry-run|--preview <空目录>|--apply]`，以及 `workspace format|generate|check --file omni.workspace.json`。详见 [通用开发指南](../../DEVELOPMENT.md)。
+
 新项目采用根目录 `main.go` 与 `internal/config、svc、logic、handler、types`。完整职责、启动扩展、流式接口和生成文件边界见 [项目指南](../../PROJECT.md)。

 ## 创建项目

 ```sh
 # 仓库读取权限与 PATH 配置见根目录 README
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.13.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.14.0-preview
 go-omni new --module example.com/hello ./hello

 # 从自己的契约生成；service.api 及其相对 import 文件需要在本地存在
@@ -41,14 +43,14 @@ main、Gen.go、OpenAPI 和 manifest 由生成器维护；业务文件按字节

 ## 版本与迁移

-CLI 与框架依赖固定使用 v0.13.0-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；`--framework-version` 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：
+CLI 与框架依赖固定使用 v0.14.0-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；`--framework-version` 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：

 ```sh
 # 在 go-omni 源码仓库中执行
 go run ./cmd/go-omni new --module example.com/hello --framework-dir . ../hello
 ```

-新模板需要 v0.13.0-preview 的依赖退出与端点配置能力，继续使用 manifest v2。v0.12 项目需按 [升级步骤](../../PROJECT.md#从-v012-生成项目升级) 补入 svc 生命周期字段和方法，生成器保留这些项目文件。不兼容旧目录，旧生成项目请在新目录重新生成后移入业务代码，不覆盖手写 main。独立工具命令不会被删除。受管理项目通过 `.api` 模块导入增加业务，不使用旧 `add` 命令的手动路由装配。
+新模板需要 v0.14.0-preview 的通用 Runtime、配置和绑定能力，继续使用 manifest v2。已有项目使用 [定点升级与预览](../../DEVELOPMENT.md#v013-项目升级)：原始模板可自动替换，含业务修改的基础文件按预览合并；通用清理由 Runtime 负责。独立工具命令不会被删除。受管理项目通过 `.api` 模块导入增加业务，不使用旧 `add` 命令的手动路由装配。

 ## 数据库迁移命令

--- a/cmd/go-omni/api.go
+++ b/cmd/go-omni/api.go
@@ -15,16 +15,19 @@ func runAPI(args []string) error {
 		return nil
 	}
 	command := args[0]
+	if command == "upgrade" {
+		return runUpgrade(args[1:])
+	}
 	if command == "go" {
 		command = "generate"
 	}
 	if command == "check" {
 		command = "validate"
 	}
-	if command != "new" && command != "generate" && command != "validate" && command != "inspect" && command != "export" {
+	if command != "new" && command != "generate" && command != "validate" && command != "inspect" && command != "export" && command != "format" {
 		return fmt.Errorf("unknown api command %q", command)
 	}
-	readOnly := command == "validate" || command == "inspect" || command == "export"
+	readOnly := command == "validate" || command == "inspect" || command == "export" || command == "format"
 	o := apigen.Options{}
 	for i := 1; i < len(args); i++ {
 		arg := args[i]
@@ -33,7 +36,7 @@ func runAPI(args []string) error {
 			return nil
 		}
 		if arg == "--check" || arg == "--dry-run" {
-			if command != "generate" {
+			if command != "generate" && !(command == "format" && arg == "--check") {
 				return fmt.Errorf("%s belongs to api generate", arg)
 			}
 			if arg == "--check" {
@@ -108,6 +111,14 @@ func runAPI(args []string) error {
 			return err
 		}
 	}
+	if command == "format" {
+		changes, err := apigen.FormatProject(o.API, o.Check)
+		if err != nil {
+			return err
+		}
+		fmt.Printf("API format: %d files updated\n", len(changes))
+		return nil
+	}
 	if readOnly {
 		spec, err := apigen.Parse(o.API)
 		if err != nil {
--- a/cmd/go-omni/apigen/business_test.go
+++ b/cmd/go-omni/apigen/business_test.go
@@ -0,0 +1,91 @@
+package apigen
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestBusinessContract(t *testing.T) {
+	spec, err := Parse(filepath.Join(frameworkRoot(t), "examples/contracts/business.api"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	c, err := Compile(spec)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var doc map[string]any
+	if err = json.Unmarshal(c.Document, &doc); err != nil {
+		t.Fatal(err)
+	}
+	paths := doc["paths"].(map[string]any)
+	body := paths["/optional"].(map[string]any)["post"].(map[string]any)["requestBody"].(map[string]any)
+	if body["required"] != false {
+		t.Fatal("optional body documented as required")
+	}
+	for _, path := range []string{"/empty", "/absent"} {
+		if paths[path].(map[string]any)["post"].(map[string]any)["x-omni-request-policy"] == nil {
+			t.Fatal("missing policy metadata")
+		}
+	}
+}
+func TestBusinessGeneratedProject(t *testing.T) {
+	if os.Getenv("GO_OMNI_SCAFFOLD_INTEGRATION") != "1" {
+		t.Skip("set GO_OMNI_SCAFFOLD_INTEGRATION=1")
+	}
+	dir := filepath.Join(t.TempDir(), "business")
+	o := Options{Dir: dir, API: filepath.Join(frameworkRoot(t), "examples/contracts/business.api"), Module: "example.com/business", FrameworkDir: frameworkRoot(t)}
+	if err := generateManagedTestProject(t, o); err != nil {
+		t.Fatal(err)
+	}
+	for _, name := range []string{"upload", "nullable", "nothing", "rawNull", "rawArray", "empty", "absent", "optional", "echo", "tolerant", "noContent"} {
+		writeFile(t, filepath.Join(dir, "internal/logic/demo/"+name+".go"), "package demo\n")
+	}
+	writeFile(t, filepath.Join(dir, "internal/logic/demo/list.go"), readFile(t, "testdata/business/operations.go"))
+	writeFile(t, filepath.Join(dir, "consumer_test.go"), readFile(t, "testdata/business/consumer_test.go"))
+	writeFile(t, filepath.Join(dir, "internal/middleware/accessFactory.go"), readFile(t, "testdata/business/accessFactory.go"))
+	writeFile(t, filepath.Join(dir, "internal/svc/client.go"), readFile(t, "testdata/business/client.go"))
+	svcFile := filepath.Join(dir, "internal/svc/serviceContext.go")
+	source := strings.Replace(readFile(t, svcFile), "type ServiceContext struct {", "type ServiceContext struct {\n Client *accessClient", 1)
+	source = strings.Replace(source, "return nil", "return c.initAccess(ctx)", 1)
+	writeFile(t, svcFile, source)
+	o.API = filepath.Join(dir, "api/business.api")
+	o.Check = true
+	if err := generateManagedTestProject(t, o); err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 90*time.Second)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, "go", "test", "-race", "-mod=mod", "-count=1", "./...")
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(), "GOWORK=off")
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if os.Getenv("GO_OMNI_RELEASE_CLI") != "" {
+		cmd = exec.CommandContext(ctx, "go", "list", "-m", "-json", frameworkModule)
+		cmd.Dir = dir
+		cmd.Env = append(os.Environ(), "GOWORK=off")
+		raw, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatal(err, string(raw))
+		}
+		var module struct {
+			Version, Sum string
+			Replace      any
+		}
+		if err = json.Unmarshal(raw, &module); err != nil {
+			t.Fatal(err)
+		}
+		if module.Version != os.Getenv("GO_OMNI_RELEASE_VERSION") || module.Replace != nil || module.Sum == "" {
+			t.Fatal("not a fixed remote consumer")
+		}
+		t.Logf("remote framework %s checksum %s; no local replace", module.Version, module.Sum)
+	}
+}
--- a/cmd/go-omni/apigen/catalogDocument.go
+++ b/cmd/go-omni/apigen/catalogDocument.go
@@ -0,0 +1,69 @@
+package apigen
+
+import (
+	"errors"
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"git.yuntuo.hk/k2safe/go-omni/response"
+	"io"
+	"os"
+	"path/filepath"
+)
+
+const catalogDocumentFile = "omni.errors.json"
+
+func readDocumentCatalog(root string, spec *Spec) error {
+	path := filepath.Join(root, catalogDocumentFile)
+	stat, err := os.Lstat(path)
+	if errors.Is(err, os.ErrNotExist) {
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	if !stat.Mode().IsRegular() {
+		return errors.New("api: error metadata must be a regular file")
+	}
+	file, err := os.Open(path)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+	raw, err := io.ReadAll(io.LimitReader(file, (1<<20)+1))
+	if err != nil {
+		return err
+	}
+	if len(raw) > 1<<20 {
+		return errors.New("api: error metadata exceeds 1 MiB")
+	}
+	var catalog apierrors.Catalog
+	if err = apierrors.DecodeCatalogJSON(raw, &catalog); err != nil {
+		return err
+	}
+	registry, err := apierrors.NewRegistry(catalog)
+	if err != nil {
+		return err
+	}
+	normalized := registry.Catalog()
+	spec.DocumentCatalog = &normalized
+	spec.Sources[catalogDocumentFile] = raw
+	spec.SourcePaths[catalogDocumentFile] = path
+	return nil
+}
+func validateDocumentCatalog(spec *Spec) error {
+	if spec.DocumentCatalog == nil {
+		return nil
+	}
+	for _, r := range spec.Routes {
+		if len(r.Errors) > 0 {
+			continue
+		}
+		policy, err := response.New(responseConfig(spec, r))
+		if err != nil {
+			return err
+		}
+		if err = policy.ValidateErrors(*spec.DocumentCatalog); err != nil {
+			return err
+		}
+	}
+	return nil
+}
--- a/cmd/go-omni/apigen/compile.go
+++ b/cmd/go-omni/apigen/compile.go
@@ -40,8 +40,17 @@ func Compile(spec *Spec) (*Compiled, error) {
 	if prepareErr != nil {
 		return nil, prepareErr
 	}
+	if err := validateDocumentCatalog(spec); err != nil {
+		return nil, err
+	}
+	if err := spec.RequestPolicy.Validate(); err != nil {
+		return nil, err
+	}
 	definitions := map[string]Type{}
 	for _, t := range spec.Types {
+		if t.Name == "File" {
+			return nil, errors.New("File is reserved for multipart uploads")
+		}
 		if t.Name == "ContractScalars" && len(spec.Scalars) > 0 {
 			return nil, errors.New("ContractScalars is reserved when declaring scalars")
 		}
@@ -61,7 +70,7 @@ func Compile(spec *Spec) (*Compiled, error) {
 	resolving := map[string]bool{}
 	var resolve func(string, int) (reflect.Type, error)
 	var expression func(ast.Expr, int) (reflect.Type, error)
-	primitives := map[string]reflect.Type{"any": reflect.TypeOf((*any)(nil)).Elem(), "string": reflect.TypeOf(""), "bool": reflect.TypeOf(false), "int": reflect.TypeOf(int(0)), "int8": reflect.TypeOf(int8(0)), "int16": reflect.TypeOf(int16(0)), "int32": reflect.TypeOf(int32(0)), "int64": reflect.TypeOf(int64(0)), "uint": reflect.TypeOf(uint(0)), "uint8": reflect.TypeOf(uint8(0)), "uint16": reflect.TypeOf(uint16(0)), "uint32": reflect.TypeOf(uint32(0)), "uint64": reflect.TypeOf(uint64(0)), "float32": reflect.TypeOf(float32(0)), "float64": reflect.TypeOf(float64(0))}
+	primitives := map[string]reflect.Type{"File": reflect.TypeOf(contract.File{}), "any": reflect.TypeOf((*any)(nil)).Elem(), "string": reflect.TypeOf(""), "bool": reflect.TypeOf(false), "int": reflect.TypeOf(int(0)), "int8": reflect.TypeOf(int8(0)), "int16": reflect.TypeOf(int16(0)), "int32": reflect.TypeOf(int32(0)), "int64": reflect.TypeOf(int64(0)), "uint": reflect.TypeOf(uint(0)), "uint8": reflect.TypeOf(uint8(0)), "uint16": reflect.TypeOf(uint16(0)), "uint32": reflect.TypeOf(uint32(0)), "uint64": reflect.TypeOf(uint64(0)), "float32": reflect.TypeOf(float32(0)), "float64": reflect.TypeOf(float64(0))}
 	expression = func(e ast.Expr, depth int) (reflect.Type, error) {
 		if depth > 32 {
 			return nil, errors.New("type nesting exceeds 32")
@@ -138,7 +147,7 @@ func Compile(spec *Spec) (*Compiled, error) {
 			if err != nil {
 				return nil, fmt.Errorf("%s.%s: %w", name, f.Name, err)
 			}
-			fields = append(fields, reflect.StructField{Name: f.Name, Type: t, Tag: reflect.StructTag(f.Tag)})
+			fields = append(fields, reflect.StructField{Name: f.Name, Type: t, Tag: reflect.StructTag(fieldTag(f))})
 		}
 		t := reflect.StructOf(fields)
 		resolved[name] = t
@@ -162,7 +171,7 @@ func Compile(spec *Spec) (*Compiled, error) {
 	}
 	handlers, paths, shapes, groups := map[string]bool{}, map[string]bool{}, map[string]string{}, map[string]bool{}
 	middlewareSymbols := map[string]string{}
-	for _, r := range spec.Routes {
+	for routeIndex, r := range spec.Routes {
 		if !goName.MatchString(r.Handler) {
 			return nil, fmt.Errorf("%s: invalid handler name", r.Position)
 		}
@@ -233,14 +242,26 @@ func Compile(spec *Spec) (*Compiled, error) {
 		if err := validateRouteExtensions(r); err != nil {
 			return nil, fmt.Errorf("%s: %w", r.Position, err)
 		}
+		effectivePolicy := contract.MergePolicy(spec.RequestPolicy, r.RequestPolicy)
+		if (r.Method == "get" || r.Method == "head") && effectivePolicy.Body != "" && effectivePolicy.Body != "auto" && effectivePolicy.Body != "none" {
+			return nil, errors.New("GET/HEAD cannot inherit a JSON body policy; override body with auto or none")
+		}
 		op := openapi.Operation{Method: r.Method, Path: r.Path, OperationID: operationID(r), Summary: r.Summary, Responses: map[int]openapi.Response{}}
 		if r.Request != "" {
 			b, ok := c.Bindings[r.Request]
 			if !ok {
 				return nil, fmt.Errorf("unknown request %s", r.Request)
 			}
+			r.BoundMultipart = b.HasMultipart() && !r.CustomBinding && !r.Manual
+			spec.Routes[routeIndex].BoundMultipart = r.BoundMultipart
+			if b.HasMultipart() && r.BodyMode != "multipart" {
+				return nil, errors.New("multipart fields require @body (mode: multipart)")
+			}
 			op.Parameters = b.Parameters()
 			op.Request = b.BodySchema()
+			if op.Request != nil && (effectivePolicy.Body == "none" || effectivePolicy.Body == "emptyObject") {
+				return nil, errors.New("request policy conflicts with JSON fields")
+			}
 			if op.Request != nil && (r.BodyMode == "raw" || r.BodyMode == "multipart") {
 				return nil, errors.New("raw/multipart request DTOs may declare only path/form/header fields; use the generated body stream for content")
 			}
@@ -250,11 +271,7 @@ func Compile(spec *Spec) (*Compiled, error) {
 		}
 		var response *openapi.Schema
 		if r.Response != "" {
-			b, ok := c.Bindings[r.Response]
-			if !ok {
-				return nil, fmt.Errorf("unknown response %s", r.Response)
-			}
-			s, err := b.ResponseSchema()
+			s, err := responseDataSchema(r.Response, c.Bindings)
 			if err != nil {
 				return nil, err
 			}
@@ -295,7 +312,7 @@ func Compile(spec *Spec) (*Compiled, error) {
 	if err = decoder.Decode(&doc); err != nil {
 		return nil, err
 	}
-	decorateDocument(doc, spec)
+	decorateDocument(doc, spec, c.Bindings)
 	c.Document, err = json.MarshalIndent(doc, "", "  ")
 	return c, err
 }
--- a/cmd/go-omni/apigen/contractChanges.go
+++ b/cmd/go-omni/apigen/contractChanges.go
@@ -90,7 +90,8 @@ func snapshotContract(spec *Spec) *contractSnapshot {
 			}
 		}
 		visit(r.Request)
-		visit(r.Response)
+		_, responseName := responseShape(r.Response)
+		visit(responseName)
 		op := routeContract{
 			Method: strings.ToUpper(r.Method), Path: r.Path, Group: r.Group, Handler: r.Handler,
 			Request: r.Request, Response: r.Response, BodyMode: r.BodyMode, Produces: r.Produces,
@@ -223,14 +224,14 @@ func expectedLogicSignature(r Route) string {
 	if r.Request != "" {
 		params = append(params, "*types."+r.Request)
 	}
-	if r.BodyMode == "raw" || r.BodyMode == "multipart" {
+	if streamsBody(r) {
 		params = append(params, "*httpx.Body")
 	}
 	results := []string{"error"}
 	if r.Produces != "" {
 		results = []string{"*httpx.Stream", "error"}
-	} else if r.Response != "" {
-		results = []string{"*types." + r.Response, "error"}
+	} else if result := responseGoType(r.Response); result != "" {
+		results = []string{result, "error"}
 	}
 	return displaySignature(upper(r.Handler), params, results)
 }
--- a/cmd/go-omni/apigen/contractMetadata.go
+++ b/cmd/go-omni/apigen/contractMetadata.go
@@ -3,6 +3,7 @@ package apigen
 import (
 	"encoding/json"
 	"fmt"
+	"git.yuntuo.hk/k2safe/go-omni/contract"
 	"net/http"
 	"regexp"
 	"sort"
@@ -119,7 +120,8 @@ func prepareMetadata(original *Spec) (*Spec, error) {
 	return &spec, nil
 }

-func decorateDocument(doc map[string]any, spec *Spec) {
+func decorateDocument(doc map[string]any, spec *Spec, bindings map[string]*contract.Binder) {
+	doc["x-omni-contract-sources"] = sourceMetadata(spec)
 	if spec.DefaultResponse != "" {
 		doc["x-omni-default-response"] = spec.DefaultResponse
 	}
@@ -144,7 +146,12 @@ func decorateDocument(doc map[string]any, spec *Spec) {
 	}
 	doc["components"].(map[string]any)["securitySchemes"] = schemes
 	definitions := map[string]ErrorDefinition{}
-	registry := apierrors.MustRegistry(errorCatalog(spec, nil))
+	declaredRegistry := apierrors.MustRegistry(errorCatalog(spec, nil))
+	var documentRegistry *apierrors.Registry
+	if spec.DocumentCatalog != nil {
+		documentRegistry = apierrors.MustRegistry(*spec.DocumentCatalog)
+		doc["x-omni-app-error-catalog"] = documentRegistry.Catalog()
+	}
 	for _, e := range spec.Errors {
 		definitions[e.Name] = e
 	}
@@ -152,6 +159,7 @@ func decorateDocument(doc map[string]any, spec *Spec) {
 		doc["x-omni-errors"] = spec.Errors
 	}
 	for _, r := range spec.Routes {
+		registry := declaredRegistry
 		policy := response.MustNew(responseConfig(spec, r))
 		cfg := policy.Config()
 		parts := strings.Split(r.Path, "/")
@@ -161,7 +169,16 @@ func decorateDocument(doc map[string]any, spec *Spec) {
 			}
 		}
 		op := doc["paths"].(map[string]any)[strings.Join(parts, "/")].(map[string]any)[r.Method].(map[string]any)
-		decorateRequestOptions(op, r)
+		requestRoute := r
+		requestRoute.RequestPolicy = contract.MergePolicy(spec.RequestPolicy, r.RequestPolicy)
+		decorateRequestOptions(op, requestRoute)
+		if b := bindings[r.Request]; b != nil && b.HasMultipart() {
+			encoding := map[string]any{}
+			for _, name := range b.MultipartJSONFields() {
+				encoding[name] = map[string]any{"contentType": "application/json"}
+			}
+			op["requestBody"] = map[string]any{"required": true, "content": map[string]any{"multipart/form-data": map[string]any{"schema": b.MultipartSchema(), "encoding": encoding}}}
+		}
 		if r.ResponseFormat != "" {
 			op["x-omni-response"] = r.ResponseFormat
 		}
@@ -193,6 +210,13 @@ func decorateDocument(doc map[string]any, spec *Spec) {
 			e := definitions[name]
 			grouped[e.Status] = append(grouped[e.Status], e)
 		}
+		if len(r.Errors) == 0 && documentRegistry != nil {
+			registry = documentRegistry
+			op["x-omni-error-catalog-scope"] = "app"
+			for key, definition := range registry.Catalog().Definitions {
+				grouped[definition.Status] = append(grouped[definition.Status], ErrorDefinition{Name: key, Code: key, Status: definition.Status, Message: definition.Message, BusinessCode: definition.Code, Params: definition.Params})
+			}
+		}
 		if len(r.Errors) > 0 {
 			op["x-omni-errors"] = r.Errors
 		}
--- a/cmd/go-omni/apigen/documentation_test.go
+++ b/cmd/go-omni/apigen/documentation_test.go
@@ -0,0 +1,127 @@
+package apigen
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestFieldDocumentationAndFormat(t *testing.T) {
+	source := "// 项目说明\n  type Req{\n// 状态\n State int `json:\"state,options=0|1\" example:\"1\" enumDescriptions:\"[\\\"禁用\\\",\\\"启用\\\"]\"` // 状态值\n /* 第一行\n 第二行 */\nName string `json:\"name\" example:\"企业名称\"`\n}\nservice demo{\n @handler echo\npost /echo (Req) returns (Req)\n}\n"
+	formatted, err := Format([]byte(source))
+	if err != nil {
+		t.Fatal(err)
+	}
+	again, err := Format(formatted)
+	if err != nil || !bytes.Equal(formatted, again) {
+		t.Fatal("format is not idempotent", err, string(again))
+	}
+	if !bytes.Contains(formatted, []byte("    // 状态\n    State")) {
+		t.Fatal(string(formatted))
+	}
+	spec, err := parseText(t, string(formatted))
+	if err != nil {
+		t.Fatal(err)
+	}
+	c, err := Compile(spec)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if spec.Types[0].Fields[0].Description != "状态\n状态值" || spec.Types[0].Fields[1].Description != "第一行\n第二行" {
+		t.Fatalf("%+v", spec.Types[0].Fields)
+	}
+	schema, err := c.Bindings["Req"].ResponseSchema()
+	if err != nil {
+		t.Fatal(err)
+	}
+	state := schema.Properties["state"]
+	if state.Description != "状态\n状态值" || len(state.EnumDescriptions) != 2 || state.Example != json.Number("1") {
+		t.Fatalf("%+v", state)
+	}
+	dir := t.TempDir()
+	entry := filepath.Join(dir, "demo.api")
+	writeFile(t, entry, source)
+	if _, err = FormatProject(entry, true); err == nil {
+		t.Fatal("check accepted drift")
+	}
+	if readFile(t, entry) != source {
+		t.Fatal("check wrote source")
+	}
+	if _, err = FormatProject(entry, false); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = FormatProject(entry, true); err != nil {
+		t.Fatal(err)
+	}
+	project := filepath.Join(t.TempDir(), "demo")
+	if _, err = Generate(Options{API: entry, Dir: project, Module: "example.com/docs", FrameworkDir: frameworkRoot(t)}); err != nil {
+		t.Fatal(err)
+	}
+	dto := readFile(t, filepath.Join(project, "internal/types/"+dtoFile("demo.api:1:1")))
+	if !strings.Contains(dto, "// 状态值") || !strings.Contains(dto, `description:"状态\n状态值"`) {
+		t.Fatal(dto)
+	}
+	// Invalid examples fail before project output is created.
+	bad := strings.Replace(source, "example:\"1\"", "example:\"9\"", 1)
+	writeFile(t, entry, bad)
+	if _, err = FormatProject(entry, false); err == nil {
+		t.Fatal("invalid enum example accepted")
+	}
+	if data, _ := os.ReadFile(entry); string(data) != bad {
+		t.Fatal("invalid source changed")
+	}
+}
+
+func TestFormatAlignsFieldsAndPreservesTokens(t *testing.T) {
+	source := []byte("type Req {\n Name string `json:\"name\"` // 名称\n  Sequence int64 `json:\"sequence\"` // 编号\n}\n")
+	out, err := Format(source)
+	if err != nil {
+		t.Fatal(err)
+	}
+	again, err := Format(out)
+	if err != nil || !bytes.Equal(out, again) {
+		t.Fatal("alignment not idempotent", err)
+	}
+	lines := strings.Split(string(out), "\n")
+	if strings.Index(lines[1], "`") != strings.Index(lines[2], "`") || strings.Index(lines[1], "//") != strings.Index(lines[2], "//") {
+		t.Fatal("fields not aligned", string(out))
+	}
+	for _, literal := range []string{"`json:\"name\"`", "`json:\"sequence\"`", "// 名称", "// 编号"} {
+		if !bytes.Contains(out, []byte(literal)) {
+			t.Fatal("literal changed", literal)
+		}
+	}
+}
+
+func TestRequestPolicyCannotCreateGETBody(t *testing.T) {
+	for _, source := range []string{
+		"service demo { @handler get\n @request(body: required)\n get /x }",
+		"@app(request: {\"body\":\"optional\"})\n service demo { @handler get\n get /x }",
+	} {
+		spec, err := parseText(t, source)
+		if err == nil {
+			_, err = Compile(spec)
+		}
+		if err == nil {
+			t.Fatal("GET body policy accepted")
+		}
+	}
+}
+func TestFormatLiteralPreservation(t *testing.T) {
+	source := []byte("type Demo {\n Body string `json:\"body\"\ndescription:\"literal  space\"`\n}\n")
+	out, err := Format(source)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Contains(out, []byte("`json:\"body\"\ndescription:\"literal  space\"`")) {
+		t.Fatal(string(out))
+	}
+	for _, src := range []string{"type X {", "}", "info (title:\"unterminated)"} {
+		if _, err := Format([]byte(src)); err == nil {
+			t.Fatal("invalid input accepted")
+		}
+	}
+}
--- a/cmd/go-omni/apigen/format.go
+++ b/cmd/go-omni/apigen/format.go
@@ -0,0 +1,207 @@
+package apigen
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"text/scanner"
+	"unicode/utf8"
+)
+
+// Format normalizes indentation and blank lines without rewriting tokens,
+// comments, quoted metadata, struct tags or multiline literal contents.
+func Format(source []byte) ([]byte, error) {
+	if len(source) > 1<<20 {
+		return nil, errors.New("api: source size limit exceeded")
+	}
+	var scan scanner.Scanner
+	scan.Init(bytes.NewReader(source))
+	scan.Mode = scanner.ScanIdents | scanner.ScanInts | scanner.ScanStrings | scanner.ScanRawStrings | scanner.ScanComments
+	var scanErr error
+	scan.Error = func(s *scanner.Scanner, msg string) {
+		if scanErr == nil {
+			scanErr = fmt.Errorf("%s: %s", s.Position, msg)
+		}
+	}
+	depths := map[int]int{}
+	protected := map[int]bool{}
+	depth := 0
+	for k := scan.Scan(); k != scanner.EOF; k = scan.Scan() {
+		line := scan.Position.Line
+		value := scan.TokenText()
+		if k == '}' || k == ')' {
+			depth--
+			if depth < 0 {
+				return nil, errors.New("api: unmatched closing delimiter")
+			}
+		}
+		if _, ok := depths[line]; !ok {
+			depths[line] = depth
+		}
+		// Preserve interior lines exactly, including the closing line of a literal.
+		count := strings.Count(value, "\n")
+		for n := 1; n <= count; n++ {
+			protected[line+n] = true
+		}
+		if k == '{' || k == '(' {
+			depth++
+		}
+	}
+	if scanErr != nil {
+		return nil, scanErr
+	}
+	if depth != 0 {
+		return nil, errors.New("api: unclosed delimiter")
+	}
+	lines := strings.Split(string(source), "\n")
+	out := make([]string, 0, len(lines))
+	outProtected := map[int]bool{}
+	blank := true
+	lastDepth := 0
+	for i, line := range lines {
+		if protected[i+1] {
+			out = append(out, line)
+			outProtected[len(out)] = true
+			blank = false
+			continue
+		}
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" {
+			if !blank {
+				out = append(out, "")
+				blank = true
+			}
+			continue
+		}
+		d, ok := depths[i+1]
+		if ok {
+			lastDepth = d
+		}
+		out = append(out, strings.Repeat("    ", lastDepth)+trimmed)
+		blank = false
+	}
+	for len(out) > 0 && out[len(out)-1] == "" {
+		out = out[:len(out)-1]
+	}
+	alignFieldLines(out, outProtected)
+	return []byte(strings.Join(out, "\n") + "\n"), nil
+}
+
+// Only complete, single-line fields are aligned. Literal bytes and multiline
+// comment contents are never candidates, even when they resemble a field.
+var singleLineField = regexp.MustCompile("^([ \\t]*)([A-Z][A-Za-z0-9_]*)[ \\t]+([^ \\t`]+)[ \\t]+(`[^`]*`)[ \\t]*(//.*)?$")
+
+func alignFieldLines(lines []string, protected map[int]bool) {
+	for start := 0; start < len(lines); {
+		var fields [][]string
+		widths := [3]int{}
+		end := start
+		for end < len(lines) && !protected[end+1] {
+			parts := singleLineField.FindStringSubmatch(lines[end])
+			if parts == nil || (len(fields) > 0 && parts[1] != fields[0][1]) {
+				break
+			}
+			for col := range widths {
+				if n := utf8.RuneCountInString(parts[col+2]); n > widths[col] {
+					widths[col] = n
+				}
+			}
+			fields = append(fields, parts)
+			end++
+		}
+		for i, parts := range fields {
+			line := parts[1]
+			for col := range widths {
+				line += parts[col+2]
+				if col < 2 || parts[5] != "" {
+					line += strings.Repeat(" ", widths[col]-utf8.RuneCountInString(parts[col+2])+1)
+				}
+			}
+			lines[start+i] = line + parts[5]
+		}
+		if end == start {
+			end++
+		}
+		start = end
+	}
+}
+
+// FormatProject validates the full contract before writing any local source.
+// Check mode is read-only and reports every file needing formatting.
+func FormatProject(entry string, check bool) ([]string, error) {
+	spec, err := Parse(entry)
+	if err != nil {
+		return nil, err
+	}
+	if _, err = Compile(spec); err != nil {
+		return nil, err
+	}
+	real, err := filepath.EvalSymlinks(entry)
+	if err != nil {
+		return nil, err
+	}
+	root := filepath.Dir(real)
+	names := make([]string, 0, len(spec.Sources))
+	for name := range spec.Sources {
+		if strings.HasPrefix(name, "@") || filepath.Ext(name) != ".api" {
+			continue
+		}
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	next := map[string][]byte{}
+	var changed []string
+	for _, name := range names {
+		data, err := Format(spec.Sources[name])
+		if err != nil {
+			return nil, fmt.Errorf("%s: %w", name, err)
+		}
+		if !bytes.Equal(data, spec.Sources[name]) {
+			next[name] = data
+			changed = append(changed, name)
+		}
+	}
+	if check {
+		if len(changed) > 0 {
+			return changed, fmt.Errorf("API format drift: %s", strings.Join(changed, ", "))
+		}
+		return changed, nil
+	}
+	for _, name := range changed {
+		path := filepath.Join(root, filepath.FromSlash(name))
+		old, err := os.ReadFile(path)
+		if err != nil {
+			return changed, err
+		}
+		if !bytes.Equal(old, spec.Sources[name]) {
+			return changed, fmt.Errorf("API source changed during formatting: %s", name)
+		}
+		stat, err := os.Stat(path)
+		if err != nil {
+			return changed, err
+		}
+		f, err := os.CreateTemp(filepath.Dir(path), ".omni-format-*")
+		if err != nil {
+			return changed, err
+		}
+		tmp := f.Name()
+		err = f.Chmod(stat.Mode().Perm())
+		if err == nil {
+			_, err = f.Write(next[name])
+		}
+		err = errors.Join(err, f.Close())
+		if err == nil {
+			err = os.Rename(tmp, path)
+		}
+		_ = os.Remove(tmp)
+		if err != nil {
+			return changed, err
+		}
+	}
+	return changed, nil
+}
--- a/cmd/go-omni/apigen/generate.go
+++ b/cmd/go-omni/apigen/generate.go
@@ -19,10 +19,11 @@ import (
 )

 const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"
-const minimumVersion = "v0.13.0-preview"
+const minimumVersion = "v0.14.0-preview"
 const generatedHeader = "// Code generated by go-omni api. DO NOT EDIT.\n"

 type Options struct {
+	lockHeld                                                               bool
 	Database, Storage                                                      string
 	API, Dir, Module, FrameworkDir, FrameworkVersion, LogOutput, LogFormat string
 	Check                                                                  bool
@@ -95,6 +96,9 @@ func generate(o Options, c *Compiled, starter bool) (Output, error) {
 		return Output{}, err
 	}
 	o.Dir = directory
+	if err = checkRuntimeExtension(directory); err != nil {
+		return Output{}, err
+	}
 	for _, r := range c.Spec.Routes {
 		if !r.Manual {
 			path := filepath.Join(directory, "internal/handler", r.Group, lower(r.Handler)+"Manual.go")
@@ -109,6 +113,7 @@ func generate(o Options, c *Compiled, starter bool) (Output, error) {
 		return Output{}, err
 	}
 	seeds := map[string][]byte{}
+	requiredVersion := ""
 	moduleData, readErr := os.ReadFile(filepath.Join(directory, "go.mod"))
 	if readErr == nil {
 		mf, err := modfile.Parse("go.mod", moduleData, nil)
@@ -120,7 +125,6 @@ func generate(o Options, c *Compiled, starter bool) (Output, error) {
 		}
 		o.Module = mf.Module.Mod.Path
 		found := false
-		requiredVersion := ""
 		for _, r := range mf.Require {
 			if r.Mod.Path == frameworkModule {
 				found = true
@@ -141,13 +145,13 @@ func generate(o Options, c *Compiled, starter bool) (Output, error) {
 					if !filepath.IsAbs(path) {
 						path = filepath.Join(directory, path)
 					}
-					if _, err := os.Stat(filepath.Join(path, "lifecycle", "controller.go")); err == nil {
+					if _, err := os.Stat(filepath.Join(path, "lifecycle", "runtime.go")); err == nil {
 						localCurrent = true
 					}
 				}
 			}
 			if !localCurrent {
-				return Output{}, fmt.Errorf("existing framework dependency predates dependency shutdown and configurable endpoint support; use %s or a current local replacement", minimumVersion)
+				return Output{}, fmt.Errorf("existing framework dependency predates the generated Runtime, request policy and structured MySQL support; use %s or a current local replacement", minimumVersion)
 			}
 		}
 		if o.FrameworkDir != "" {
@@ -191,7 +195,16 @@ func generate(o Options, c *Compiled, starter bool) (Output, error) {
 	// from its own api/ tree, including all imports.
 	entry := "api/" + c.Spec.Entry
 	for name, data := range c.Spec.Sources {
-		seeds["api/"+name] = data
+		if !strings.HasPrefix(name, "@") {
+			seeds["api/"+name] = data
+		}
+	}
+	if len(c.Spec.SharedRoots) > 0 {
+		raw, e := sharedSeeds(c.Spec, directory)
+		if e != nil {
+			return Output{}, e
+		}
+		seeds["api/"+importsFile] = raw
 	}
 	if o.API != "" {
 		source, _ := filepath.Abs(o.API)
@@ -200,6 +213,7 @@ func generate(o Options, c *Compiled, starter bool) (Output, error) {
 		rel, e := filepath.Rel(targetReal, sourceReal)
 		if e == nil && rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
 			entry = filepath.ToSlash(rel)
+			delete(seeds, "api/"+importsFile)
 			for name := range c.Spec.Sources {
 				delete(seeds, "api/"+name)
 			}
@@ -208,7 +222,7 @@ func generate(o Options, c *Compiled, starter bool) (Output, error) {
 	// Source collisions must never leave a copied contract different from the
 	// generated code. On updates, use the developer-owned API in the project.
 	for name, data := range seeds {
-		if strings.HasSuffix(name, ".api") {
+		if strings.HasSuffix(name, ".api") || filepath.Base(name) == catalogDocumentFile || filepath.Base(name) == importsFile {
 			current, e := os.ReadFile(filepath.Join(directory, filepath.FromSlash(name)))
 			if e == nil && string(current) != string(data) {
 				return Output{}, fmt.Errorf("%s already differs; regenerate from that project API instead", name)
@@ -227,7 +241,12 @@ func generate(o Options, c *Compiled, starter bool) (Output, error) {
 			}
 		}
 	}
-	return apply(directory, o.Module, entry, generated, seeds, o.Check, o.DryRun, o.profile(), snapshotContract(c.Spec))
+	out, err := apply(directory, o.Module, entry, generated, seeds, o.Check, o.DryRun, o.profile(), snapshotContract(c.Spec), o.lockHeld)
+	if requiredVersion != "" && requiredVersion != minimumVersion {
+		out.Diagnostics = append(out.Diagnostics, Diagnostic{Severity: "review", Code: "frameworkVersion", Path: "go.mod", Before: requiredVersion, After: minimumVersion, Message: "project dependency differs from this CLI template version; use matching CLI/framework versions, or verify the explicit local replacement"})
+		sortDiagnostics(out.Diagnostics)
+	}
+	return out, err
 }

 func moduleFile(o Options) ([]byte, error) {
@@ -336,6 +355,13 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 	}

 	types := "package types\n\n"
+	needsUpload := false
+	for _, b := range c.Bindings {
+		needsUpload = needsUpload || b.HasMultipart()
+	}
+	if needsUpload {
+		types += fmt.Sprintf("import %q\n", frameworkModule+"/contract")
+	}
 	if len(c.Spec.Scalars) > 0 {
 		types += "import("
 		for i, d := range c.Spec.Scalars {
@@ -350,12 +376,28 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 		registry += "}}\n"
 		put(generated, "internal/types/scalarsGen.go", generatedHeader+registry)
 	}
+	if needsUpload {
+		types += "type File = contract.File\n"
+	}
+	bySource := map[string]string{}
 	for _, t := range c.Spec.Types {
-		types += "type " + t.Name + " struct {\n"
-		for _, f := range t.Fields {
-			types += fmt.Sprintf("%s %s `%s`\n", f.Name, f.Type, f.Tag)
+		name := dtoFile(t.Position)
+		if bySource[name] == "" {
+			bySource[name] = "package types\n\n"
 		}
-		types += "}\n"
+		text := "type " + t.Name + " struct {\n"
+		for _, f := range t.Fields {
+			if f.Description != "" {
+				for _, line := range strings.Split(f.Description, "\n") {
+					text += "// " + line + "\n"
+				}
+			}
+			text += fmt.Sprintf("%s %s `%s`\n", f.Name, f.Type, fieldTag(f))
+		}
+		bySource[name] += text + "}\n"
+	}
+	for name, text := range bySource {
+		put(generated, "internal/types/"+name, generatedHeader+text)
 	}
 	put(generated, "internal/types/typesGen.go", generatedHeader+types)
 	put(generated, "docs/openapi.json", string(c.Document)+"\n")
@@ -408,8 +450,8 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 				continue
 			}
 			hasAutomatic = true
-			needsTypes = needsTypes || r.Request != "" || r.Response != ""
-			needsBinder = needsBinder || (r.Request != "" && !r.CustomBinding)
+			needsTypes = needsTypes || r.Request != "" || responseGoType(r.Response) != ""
+			needsBinder = needsBinder || !r.CustomBinding
 		}
 		text += fmt.Sprintf("%q;%q;", frameworkModule+"/httpx", o.Module+"/internal/svc")
 		if needsTypes {
@@ -442,12 +484,18 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 				put(seeds, "internal/handler/"+group+"/"+lower(r.Handler)+"Manual.go", fmt.Sprintf("package %s\nimport(%q;apierrors %q)\n// %s owns raw/multipart binding and response output. h.deps holds project dependencies.\n// This file is preserved on regeneration.\nfunc(h *Handler)%s(c *httpx.Context)error{return apierrors.New(501,\"NOT_IMPLEMENTED\",\"manual handler is not implemented\")}\n", packageName, frameworkModule+"/httpx", frameworkModule+"/errors", name, name))
 				continue
 			}
-			if r.Request != "" && !r.CustomBinding {
+			if !r.CustomBinding {
 				scalarArgs := ""
 				if len(c.Spec.Scalars) > 0 {
 					scalarArgs = "types.ContractScalars()..."
 				}
-				text += fmt.Sprintf("var %sRequest = contract.MustNew[types.%s](%s)\n", lower(r.Handler), r.Request, scalarArgs)
+				requestType := "struct{}"
+				if r.Request != "" {
+					requestType = "types." + r.Request
+				} else {
+					scalarArgs = ""
+				}
+				text += fmt.Sprintf("var %sRequest = contract.MustNew[%s](%s)\n", lower(r.Handler), requestType, scalarArgs)
 			}
 			text += fmt.Sprintf("func(h *Handler) %s(c *httpx.Context)error {\n", name)
 			call := "c.Context()"
@@ -455,16 +503,32 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 				if r.CustomBinding {
 					text += fmt.Sprintf("var req types.%s\nif err:=h.bind%s(c,&req);err!=nil{return err}\n", r.Request, name)
 					put(seeds, "internal/handler/"+group+"/"+lower(r.Handler)+"Bind.go", fmt.Sprintf("package %s\nimport(%q;%q;apierrors %q)\n// bind%s is project-owned; repeated generation preserves it.\nfunc(h *Handler)bind%s(c *httpx.Context,req *types.%s)error{return apierrors.New(501,\"BINDING_NOT_IMPLEMENTED\",\"custom binding is not implemented\")}\n", packageName, frameworkModule+"/httpx", o.Module+"/internal/types", frameworkModule+"/errors", name, name, r.Request))
+				} else if r.BoundMultipart {
+					text += fmt.Sprintf("var req types.%s\ncleanup,err:=%sRequest.BindMultipart(c.Request(),httpx.RouteParams(c.Context()),&req,contract.MultipartOptions{MaxBodyBytes:%d,MaxParts:%d,MaxFieldBytes:%d,MaxFileBytes:%d,Policy:%s});if err!=nil{return err};defer cleanup()\n", r.Request, lower(r.Handler), r.MaxBodyBytes, r.MaxParts, r.MaxFieldBytes, r.MaxFileBytes, policyLiteral(r.RequestPolicy))
 				} else {
 					limit := ""
 					if r.MaxBodyBytes > 0 {
 						limit = fmt.Sprintf(",%d", r.MaxBodyBytes)
 					}
-					text += fmt.Sprintf("var req types.%s\nif err:=%sRequest.Bind(c.Request(),httpx.RouteParams(c.Context()),&req%s);err!=nil{return err}\n", r.Request, lower(r.Handler), limit)
+					policy := r.RequestPolicy
+					if r.BodyMode == "raw" || r.BodyMode == "multipart" {
+						policy.Body = "auto"
+					}
+					text += fmt.Sprintf("var req types.%s\nif err:=%sRequest.BindWithPolicy(c.Request(),httpx.RouteParams(c.Context()),&req,%s%s);err!=nil{return err}\n", r.Request, lower(r.Handler), policyLiteral(policy), limit)
 				}
 				call += ", &req"
+			} else {
+				limit := ""
+				if r.MaxBodyBytes > 0 {
+					limit = fmt.Sprintf(",%d", r.MaxBodyBytes)
+				}
+				policy := r.RequestPolicy
+				if r.BodyMode == "raw" || r.BodyMode == "multipart" {
+					policy.Body = "auto"
+				}
+				text += fmt.Sprintf("if err:=%sRequest.BindWithPolicy(c.Request(),httpx.RouteParams(c.Context()),&struct{}{},%s%s);err!=nil{return err}\n", lower(r.Handler), policyLiteral(policy), limit)
 			}
-			streamingBody := r.BodyMode == "raw" || r.BodyMode == "multipart"
+			streamingBody := streamsBody(r)
 			if streamingBody {
 				text += fmt.Sprintf("body,err:=httpx.NewBody(c.Request(),%q);if err!=nil{return err}\n", r.BodyMode)
 				call += ",body"
@@ -475,8 +539,15 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 					text += "if err:=body.Complete();err!=nil{if resp!=nil{_ =resp.Close()};return err}\n"
 				}
 				text += fmt.Sprintf("return c.WriteStream(%d,%q,resp)\n}\n", r.Status, r.Produces)
-			} else if r.Response != "" {
-				text += fmt.Sprintf("resp,err:=h.logic.%s(%s);if err!=nil{return err};if resp==nil{return fmt.Errorf(\"%s returned a nil response\")}\n", name, call, name)
+			} else if responseGoType(r.Response) != "" {
+				text += fmt.Sprintf("resp,err:=h.logic.%s(%s);if err!=nil{return err};\n", name, call)
+				kind, _ := responseShape(r.Response)
+				if kind == "object" {
+					text += fmt.Sprintf("if resp==nil{return fmt.Errorf(%q)}\n", name+" returned a nil response")
+				}
+				if kind == "array" {
+					text += "if resp==nil{resp=make(" + responseGoType(r.Response) + ",0)}\n"
+				}
 				if streamingBody {
 					text += "if err:=body.Complete();err!=nil{return err}\n"
 				}
@@ -487,10 +558,15 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 				if streamingBody {
 					text += "if err:=body.Complete();err!=nil{return err};"
 				}
-				text += "return c.NoContent()\n}\n"
+				if r.Response == "null" {
+					method := map[int]string{200: "OK", 201: "Created", 202: "Accepted"}[r.Status]
+					text += "return c." + method + "(nil)\n}\n"
+				} else {
+					text += "return c.NoContent()\n}\n"
+				}
 			}
 			service := fmt.Sprintf("package %s\nimport(\"context\"; apierrors %q;", packageName, frameworkModule+"/errors")
-			if r.Request != "" || r.Response != "" {
+			if r.Request != "" || responseGoType(r.Response) != "" {
 				service += fmt.Sprintf("%q;", o.Module+"/internal/types")
 			}
 			if streamingBody || r.Produces != "" {
@@ -503,7 +579,7 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 				service += "s.deps.Logger.InfoContext(ctx,\"greet.called\")\nreturn &types.GreetResp{Message:fmt.Sprintf(\"Hello %s\",req.Name)},nil\n}"
 			} else {
 				service += "// TODO: implement business behavior and use s.deps for dependencies.\n"
-				if r.Response != "" || r.Produces != "" {
+				if responseGoType(r.Response) != "" || r.Produces != "" {
 					service += "return nil, "
 				} else {
 					service += "return "
@@ -549,7 +625,11 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 		return nil, nil, err
 	}
 	for name, data := range infra {
-		seeds[name] = data
+		if strings.HasSuffix(name, "Gen.go") {
+			generated[name] = append([]byte(generatedHeader), data...)
+		} else {
+			seeds[name] = data
+		}
 	}
 	if o.Storage == "local" {
 		for _, r := range c.Spec.Routes {
@@ -564,7 +644,7 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 }
 func hasResponse(routes []Route) bool {
 	for _, r := range routes {
-		if r.Response != "" && !r.Manual && r.Produces == "" {
+		if kind, _ := responseShape(r.Response); r.Response != "" && kind == "object" && !r.Manual && r.Produces == "" {
 			return true
 		}
 	}
@@ -575,17 +655,41 @@ func signature(r Route) string {
 	if r.Request != "" {
 		s += ",req *types." + r.Request
 	}
-	if r.BodyMode == "raw" || r.BodyMode == "multipart" {
+	if streamsBody(r) {
 		s += ",body *httpx.Body"
 	}
 	s += ") "
 	if r.Produces != "" {
 		return s + "(*httpx.Stream,error)"
 	}
-	if r.Response != "" {
-		s += "(*types." + r.Response + ",error)"
+	if result := responseGoType(r.Response); result != "" {
+		s += "(" + result + ",error)"
 	} else {
 		s += "error"
 	}
 	return s
 }
+
+func streamsBody(r Route) bool {
+	return r.BodyMode == "raw" || (r.BodyMode == "multipart" && !r.BoundMultipart)
+}
+
+func dtoFile(position string) string {
+	source := position
+	for i := 0; i < 2; i++ {
+		if idx := strings.LastIndex(source, ":"); idx >= 0 {
+			source = source[:idx]
+		}
+	}
+	stem := strings.TrimSuffix(filepath.Base(source), ".api")
+	var b strings.Builder
+	for _, r := range stem {
+		if r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z' || r >= '0' && r <= '9' {
+			b.WriteRune(r)
+		}
+	}
+	if b.Len() == 0 {
+		b.WriteString("contract")
+	}
+	return "dto" + upper(b.String()) + digest([]byte(source))[:12] + "Gen.go"
+}
--- a/cmd/go-omni/apigen/logicCheck.go
+++ b/cmd/go-omni/apigen/logicCheck.go
@@ -42,7 +42,7 @@ func checkLogic(root, module string, contract *contractSnapshot, seeds map[strin
 	typeExtensions := false
 	if entries, err := os.ReadDir(filepath.Join(root, "internal/types")); err == nil {
 		for _, e := range entries {
-			if sourceFile(e.Name()) && e.Name() != "typesGen.go" && e.Name() != "scalarsGen.go" {
+			if sourceFile(e.Name()) && !ownedPath("internal/types/"+e.Name()) {
 				typeExtensions = true
 			}
 		}
--- a/cmd/go-omni/apigen/managed_test.go
+++ b/cmd/go-omni/apigen/managed_test.go
@@ -82,7 +82,7 @@ func TestManagedGeneratedProject(t *testing.T) {
 	writeFile(t, configPath, strings.Replace(readFile(t, configPath), "type Config struct {", "type Config struct {\n FailInit bool `json:\"failInit\"`\n ShutdownInit bool `json:\"shutdownInit\"`", 1))
 	svcPath := filepath.Join(dir, "internal/svc/serviceContext.go")
 	source := strings.Replace(readFile(t, svcPath), "type ServiceContext struct {", "type ServiceContext struct {\n Client *Client", 1)
-	source = strings.Replace(source, "return c, nil", "if err=initClient(ctx,c);err!=nil{return nil,err}\n return c,nil", 1)
+	source = strings.Replace(source, "return nil", "return initClient(ctx,c)", 1)
 	writeFile(t, svcPath, source)
 	// Independent tooling stays outside generator ownership.
 	writeFile(t, filepath.Join(dir, "cmd/migrate/main.go"), "package main\nfunc main(){}\n")
--- a/cmd/go-omni/apigen/parse.go
+++ b/cmd/go-omni/apigen/parse.go
@@ -5,6 +5,8 @@ package apigen
 import (
 	"errors"
 	"fmt"
+	"git.yuntuo.hk/k2safe/go-omni/contract"
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
 	"io"
 	"os"
 	"path/filepath"
@@ -14,6 +16,10 @@ import (
 )

 type Spec struct {
+	DocumentCatalog                      *apierrors.Catalog
+	SharedRoots                          map[string]SharedRoot
+	SourcePaths                          map[string]string
+	RequestPolicy                        contract.RequestPolicy
 	DefaultResponse                      string
 	appDeclared                          bool
 	Title, Version, Service, Description string
@@ -32,8 +38,12 @@ type Type struct {
 	Fields   []Field
 	Position string
 }
-type Field struct{ Name, Type, Tag string }
+type Field struct{ Name, Type, Tag, Description string }
 type Route struct {
+	BoundMultipart                                           bool
+	MaxParts                                                 int
+	MaxFieldBytes, MaxFileBytes                              int64
+	RequestPolicy                                            contract.RequestPolicy
 	Manual, CustomBinding                                    bool
 	BodyMode, Produces                                       string
 	MaxBodyBytes                                             int64
@@ -51,6 +61,7 @@ type Route struct {
 }
 type token struct {
 	text, position string
+	comment        string
 	kind           rune
 	space          bool
 }
@@ -71,11 +82,15 @@ func Parse(path string) (*Spec, error) {
 		return nil, err
 	}
 	root := filepath.Dir(entry)
-	spec := &Spec{Version: "1.0.0", Sources: map[string][]byte{}, Entry: filepath.Base(entry)}
+	roots, err := readSharedRoots(root)
+	if err != nil {
+		return nil, err
+	}
+	spec := &Spec{Version: "1.0.0", SharedRoots: roots, SourcePaths: map[string]string{}, Sources: map[string][]byte{}, Entry: filepath.Base(entry)}
 	visiting, visited := map[string]bool{}, map[string]bool{}
 	total := 0
-	var visit func(string, int) error
-	visit = func(name string, depth int) error {
+	var visit func(string, string, int) error
+	visit = func(name, alias string, depth int) error {
 		if depth > 32 || len(visited)+len(visiting) >= 64 {
 			return errors.New("api: import limit exceeded")
 		}
@@ -83,9 +98,16 @@ func Parse(path string) (*Spec, error) {
 		if err != nil {
 			return err
 		}
-		rel, err := filepath.Rel(root, real)
-		if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
-			return errors.New("api: imports must stay within the entry API directory")
+		sourceRoot := root
+		if alias != "" {
+			sourceRoot = roots[alias].Path
+		}
+		rel, err := sourceWithin(sourceRoot, real)
+		if err != nil {
+			return err
+		}
+		if alias != "" {
+			rel = "@" + alias + "/" + rel
 		}
 		if filepath.Ext(real) != ".api" {
 			return errors.New("api: expected .api file")
@@ -120,18 +142,37 @@ func Parse(path string) (*Spec, error) {
 			return err
 		}
 		spec.Sources[filepath.ToSlash(rel)] = data
+		spec.SourcePaths[filepath.ToSlash(rel)] = real
 		for _, imp := range p.imports {
 			if filepath.IsAbs(imp) || strings.Contains(imp, "\\") {
 				return errors.New("api: imports must use relative slash paths")
 			}
-			if err = visit(filepath.Join(filepath.Dir(real), filepath.FromSlash(imp)), depth+1); err != nil {
+			nextAlias := alias
+			next := filepath.Join(filepath.Dir(real), filepath.FromSlash(imp))
+			if strings.HasPrefix(imp, "@") {
+				var sub string
+				var ok bool
+				nextAlias, sub, ok = strings.Cut(strings.TrimPrefix(imp, "@"), "/")
+				declared, found := roots[nextAlias]
+				if !ok || !found || sub == "" || strings.HasPrefix(sub, "/") || strings.HasPrefix(sub, "../") || filepath.ToSlash(filepath.Clean(sub)) != sub {
+					return errors.New("api: import needs a declared @root and a clean relative path")
+				}
+				next = filepath.Join(declared.Path, filepath.FromSlash(sub))
+			}
+			if err = visit(next, nextAlias, depth+1); err != nil {
 				return err
 			}
 		}
 		visited[real] = true
 		return nil
 	}
-	if err = visit(entry, 0); err != nil {
+	if err = visit(entry, "", 0); err != nil {
+		return nil, err
+	}
+	if err = readDocumentCatalog(root, spec); err != nil {
+		return nil, err
+	}
+	if err = validateSharedPins(spec); err != nil {
 		return nil, err
 	}
 	if spec.Service == "" || len(spec.Routes) == 0 {
@@ -146,7 +187,7 @@ func lex(name, source string) ([]token, error) {
 	var s scanner.Scanner
 	s.Init(strings.NewReader(source))
 	s.Filename = name
-	s.Mode = scanner.ScanIdents | scanner.ScanInts | scanner.ScanStrings | scanner.ScanRawStrings | scanner.ScanComments | scanner.SkipComments
+	s.Mode = scanner.ScanIdents | scanner.ScanInts | scanner.ScanStrings | scanner.ScanRawStrings | scanner.ScanComments
 	s.Whitespace ^= 1 << '\n'
 	var scanErr error
 	s.Error = func(s *scanner.Scanner, message string) {
@@ -156,9 +197,29 @@ func lex(name, source string) ([]token, error) {
 	}
 	var out []token
 	end := 0
+	pending := ""
+	lastLine := 0
+	lastToken := -1
 	for {
 		kind := s.Scan()
-		out = append(out, token{s.TokenText(), s.Position.String(), kind, s.Position.Offset > end})
+		if kind == scanner.Comment {
+			comment := cleanComment(s.TokenText())
+			if lastToken >= 0 && s.Position.Line == lastLine {
+				out[lastToken].comment = joinComment(out[lastToken].comment, comment)
+			} else {
+				pending = joinComment(pending, comment)
+			}
+			end = s.Position.Offset + len(s.TokenText())
+			continue
+		}
+		current := token{text: s.TokenText(), position: s.Position.String(), kind: kind, space: s.Position.Offset > end}
+		if kind != '\n' {
+			current.comment = pending
+			pending = ""
+			lastLine = s.Position.Line
+			lastToken = len(out)
+		}
+		out = append(out, current)
 		end = s.Position.Offset + len(s.TokenText())
 		if kind == scanner.EOF {
 			break
@@ -315,8 +376,20 @@ func (p *parser) parse() error {
 				if err != nil {
 					return err
 				}
-				if len(m) != 1 || m["defaultResponse"] == "" {
-					return p.err("@app requires only defaultResponse: TemplateName")
+				if len(m) == 0 {
+					return p.err("@app requires defaultResponse or request")
+				}
+				for key, value := range m {
+					switch key {
+					case "defaultResponse":
+					case "request":
+						p.spec.RequestPolicy, err = decodeRequestPolicy(value)
+						if err != nil {
+							return err
+						}
+					default:
+						return p.err("unsupported @app property " + key)
+					}
 				}
 				p.spec.DefaultResponse = m["defaultResponse"]
 				p.spec.appDeclared = true
@@ -422,6 +495,7 @@ func (p *parser) parseType() error {
 	}
 	typ := Type{Name: name, Position: pos}
 	for p.skip(); p.peek() != "}"; p.skip() {
+		description := p.tokens[p.at].comment
 		name, err := p.ident()
 		if err != nil {
 			return err
@@ -444,11 +518,13 @@ func (p *parser) parseType() error {
 		if p.tokens[p.at].kind != scanner.RawString {
 			return p.err("field source tag required")
 		}
-		tag, err := strconv.Unquote(p.next().text)
+		tagToken := p.next()
+		description = joinComment(description, tagToken.comment)
+		tag, err := strconv.Unquote(tagToken.text)
 		if err != nil {
 			return err
 		}
-		typ.Fields = append(typ.Fields, Field{Name: name, Type: expression, Tag: tag})
+		typ.Fields = append(typ.Fields, Field{Name: name, Type: expression, Tag: tag, Description: description})
 	}
 	p.next()
 	p.spec.Types = append(p.spec.Types, typ)
@@ -496,6 +572,12 @@ func (p *parser) parseService(server map[string]string) error {
 			}
 			seen[annotation] = true
 			switch annotation {
+			case "request":
+				var props map[string]string
+				props, e = p.metadata()
+				if e == nil {
+					route.RequestPolicy, e = parseRequestPolicy(props)
+				}
 			case "handlerMode":
 				mode, err := p.ident()
 				if err != nil {
@@ -589,9 +671,48 @@ func (p *parser) routeType() (string, error) {
 	if err := p.expect("("); err != nil {
 		return "", err
 	}
+	prefix := ""
+	if p.peek() == "[" {
+		p.next()
+		if err := p.expect("]"); err != nil {
+			return "", err
+		}
+		prefix = "[]"
+	} else if p.peek() == "*" {
+		p.next()
+		prefix = "*"
+	}
 	name, err := p.ident()
 	if err != nil {
 		return "", err
 	}
-	return name, p.expect(")")
+	return prefix + name, p.expect(")")
+}
+
+func joinComment(a, b string) string {
+	if a == "" {
+		return b
+	}
+	if b == "" {
+		return a
+	}
+	return a + "\n" + b
+}
+func cleanComment(s string) string {
+	if strings.HasPrefix(s, "//") {
+		return strings.TrimSpace(strings.TrimPrefix(s, "//"))
+	}
+	s = strings.TrimSuffix(strings.TrimPrefix(s, "/*"), "*/")
+	lines := strings.Split(s, "\n")
+	for i, line := range lines {
+		lines[i] = strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(line), "*"))
+	}
+	return strings.TrimSpace(strings.Join(lines, "\n"))
+}
+func fieldTag(f Field) string {
+	tags, err := contract.ParseTags(f.Tag)
+	if err != nil || f.Description == "" || tags["description"] != "" {
+		return f.Tag
+	}
+	return f.Tag + " description:" + strconv.Quote(f.Description)
 }
--- a/cmd/go-omni/apigen/requestOptions.go
+++ b/cmd/go-omni/apigen/requestOptions.go
@@ -1,9 +1,11 @@
 package apigen

 import (
+	"encoding/json"
 	"errors"
 	"fmt"
 	"git.yuntuo.hk/k2safe/go-omni/contract"
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
 	"mime"
 	"strconv"
 	"strings"
@@ -16,6 +18,21 @@ func (p *parser) parseBody(r *Route) error {
 	}
 	for key, value := range props {
 		switch key {
+		case "maxParts":
+			r.MaxParts, err = strconv.Atoi(value)
+			if err != nil || r.MaxParts < 1 || r.MaxParts > 10000 {
+				return p.err("maxParts must be 1..10000")
+			}
+		case "maxFieldBytes", "maxFileBytes":
+			limit, e := strconv.ParseInt(value, 10, 64)
+			if e != nil || limit < 1 || limit > 1<<30 {
+				return p.err("part limits must be 1..1073741824 bytes")
+			}
+			if key == "maxFieldBytes" {
+				r.MaxFieldBytes = limit
+			} else {
+				r.MaxFileBytes = limit
+			}
 		case "mode":
 			r.BodyMode = value
 		case "maxBytes":
@@ -33,6 +50,16 @@ func (p *parser) parseBody(r *Route) error {
 	return nil
 }
 func validateRouteExtensions(r Route) error {
+	if (r.MaxParts > 0 || r.MaxFieldBytes > 0 || r.MaxFileBytes > 0) && r.BodyMode != "multipart" {
+		return errors.New("part limits require multipart mode")
+	}
+
+	if err := r.RequestPolicy.Validate(); err != nil {
+		return err
+	}
+	if (r.BodyMode == "raw" || r.BodyMode == "multipart") && r.RequestPolicy.Body != "" && r.RequestPolicy.Body != "auto" {
+		return errors.New("raw/multipart cannot declare a JSON body policy")
+	}
 	if r.BodyMode != "" && r.BodyMode != "json" && r.BodyMode != "raw" && r.BodyMode != "multipart" {
 		return errors.New("body mode must be json, raw or multipart")
 	}
@@ -42,6 +69,9 @@ func validateRouteExtensions(r Route) error {
 	if r.MaxBodyBytes > 0 && (r.Method == "get" || r.Method == "head") {
 		return errors.New("GET/HEAD cannot declare a body limit")
 	}
+	if (r.Method == "get" || r.Method == "head") && r.RequestPolicy.Body != "" && r.RequestPolicy.Body != "auto" && r.RequestPolicy.Body != "none" {
+		return errors.New("GET/HEAD cannot declare a JSON body policy")
+	}
 	if r.Produces != "" {
 		media, params, err := mime.ParseMediaType(r.Produces)
 		if err != nil || len(params) != 0 || media != r.Produces || strings.Contains(media, "*") {
@@ -58,6 +88,23 @@ func validateRouteExtensions(r Route) error {
 }

 func decorateRequestOptions(op map[string]any, r Route) {
+	if r.BodyMode == "raw" || r.BodyMode == "multipart" {
+		r.RequestPolicy.Body = "auto"
+	}
+	op["x-omni-request-policy"] = r.RequestPolicy
+	if r.BodyMode == "multipart" {
+		limits, _ := (contract.MultipartOptions{MaxBodyBytes: r.MaxBodyBytes, MaxParts: r.MaxParts, MaxFieldBytes: r.MaxFieldBytes, MaxFileBytes: r.MaxFileBytes}).Normalized()
+		op["x-omni-multipart-limits"] = map[string]any{"maxBytes": limits.MaxBodyBytes, "maxParts": limits.MaxParts, "maxFieldBytes": limits.MaxFieldBytes, "maxFileBytes": limits.MaxFileBytes}
+	}
+	if r.BodyMode != "raw" && r.BodyMode != "multipart" {
+		if body, ok := op["requestBody"].(map[string]any); ok && r.RequestPolicy.Body == "optional" {
+			body["required"] = false
+		}
+		if _, ok := op["requestBody"]; !ok && (r.RequestPolicy.Body == "emptyObject" || r.RequestPolicy.Body == "required" || r.RequestPolicy.Body == "optional") {
+			op["requestBody"] = map[string]any{"required": r.RequestPolicy.Body != "optional", "content": map[string]any{"application/json": map[string]any{"schema": map[string]any{"type": "object", "additionalProperties": false}}}}
+		}
+	}
+
 	if r.Manual {
 		op["x-omni-handler-mode"] = "manual"
 	}
@@ -87,3 +134,21 @@ func decorateRequestOptions(op map[string]any, r Route) {
 		op["responses"].(map[string]any)[strconv.Itoa(r.Status)] = map[string]any{"description": "Success", "content": map[string]any{r.Produces: map[string]any{"schema": schema}}}
 	}
 }
+
+func parseRequestPolicy(props map[string]string) (contract.RequestPolicy, error) {
+	data, err := json.Marshal(props)
+	if err != nil {
+		return contract.RequestPolicy{}, err
+	}
+	return decodeRequestPolicy(string(data))
+}
+func decodeRequestPolicy(raw string) (contract.RequestPolicy, error) {
+	var p contract.RequestPolicy
+	if err := apierrors.DecodeCatalogJSON([]byte(raw), &p); err != nil {
+		return p, fmt.Errorf("request policy: %w", err)
+	}
+	return p, p.Validate()
+}
+func policyLiteral(p contract.RequestPolicy) string {
+	return fmt.Sprintf("contract.RequestPolicy{UnknownQuery:%q,UTF8:%q,Charset:%q,Body:%q}", p.UnknownQuery, p.UTF8, p.Charset, p.Body)
+}
--- a/cmd/go-omni/apigen/responseShape.go
+++ b/cmd/go-omni/apigen/responseShape.go
@@ -0,0 +1,54 @@
+package apigen
+
+import (
+	"fmt"
+	"git.yuntuo.hk/k2safe/go-omni/contract"
+	"git.yuntuo.hk/k2safe/go-omni/openapi"
+	"strings"
+)
+
+// Response roots deliberately allow named DTOs, []DTO, *DTO and null. Keeping
+// these four shapes explicit makes nil/empty behavior uniform across encoders.
+func responseShape(value string) (kind, name string) {
+	if value == "null" {
+		return "null", ""
+	}
+	if strings.HasPrefix(value, "[]") {
+		return "array", strings.TrimPrefix(value, "[]")
+	}
+	if strings.HasPrefix(value, "*") {
+		return "nullable", strings.TrimPrefix(value, "*")
+	}
+	return "object", value
+}
+func responseGoType(value string) string {
+	kind, name := responseShape(value)
+	if kind == "null" || value == "" {
+		return ""
+	}
+	if kind == "array" {
+		return "[]types." + name
+	}
+	return "*types." + name
+}
+func responseDataSchema(value string, bindings map[string]*contract.Binder) (*openapi.Schema, error) {
+	kind, name := responseShape(value)
+	if kind == "null" {
+		return &openapi.Schema{Type: "object", Nullable: true, Enum: []any{nil}}, nil
+	}
+	b, ok := bindings[name]
+	if !ok {
+		return nil, fmt.Errorf("unknown response DTO %q; use Name, []Name, *Name or null", name)
+	}
+	s, err := b.ResponseSchema()
+	if err != nil {
+		return nil, err
+	}
+	switch kind {
+	case "array":
+		return &openapi.Schema{Type: "array", Items: s}, nil
+	case "nullable":
+		s.Nullable = true
+	}
+	return s, nil
+}
--- a/cmd/go-omni/apigen/shared.go
+++ b/cmd/go-omni/apigen/shared.go
@@ -0,0 +1,150 @@
+package apigen
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+const importsFile = "omni.imports.json"
+
+// SharedRoot explicitly authorizes reads from one canonical local directory.
+// Version is a project-owned label; SHA256 optionally pins the imported source
+// set, not a remote tag. The CLI never downloads or executes shared contracts.
+type SharedRoot struct {
+	Path    string `json:"path"`
+	Version string `json:"version,omitempty"`
+	SHA256  string `json:"sha256,omitempty"`
+}
+type sharedConfig struct {
+	Roots map[string]SharedRoot `json:"roots"`
+}
+
+func readSharedRoots(root string) (map[string]SharedRoot, error) {
+	stat, err := os.Lstat(filepath.Join(root, importsFile))
+	if errors.Is(err, os.ErrNotExist) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	if !stat.Mode().IsRegular() {
+		return nil, errors.New("api: shared root configuration must be a regular file")
+	}
+	f, err := os.Open(filepath.Join(root, importsFile))
+	if errors.Is(err, os.ErrNotExist) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	raw, err := io.ReadAll(io.LimitReader(f, 65537))
+	if err != nil {
+		return nil, err
+	}
+	if len(raw) > 65536 {
+		return nil, errors.New("api: shared root config too large")
+	}
+	var cfg sharedConfig
+	if err = apierrors.DecodeCatalogJSON(raw, &cfg); err != nil {
+		return nil, err
+	}
+	if len(cfg.Roots) > 16 {
+		return nil, errors.New("api: at most 16 shared roots")
+	}
+	for name, r := range cfg.Roots {
+		if !lowerName.MatchString(name) || r.Path == "" || len(r.Version) > 128 {
+			return nil, errors.New("api: invalid shared root")
+		}
+		if r.SHA256 != "" && (len(r.SHA256) != 64 || strings.Trim(r.SHA256, "0123456789abcdef") != "") {
+			return nil, errors.New("api: shared sha256 must be 64 lowercase hex characters")
+		}
+		path := r.Path
+		if !filepath.IsAbs(path) {
+			path = filepath.Join(root, path)
+		}
+		r.Path, err = filepath.EvalSymlinks(path)
+		if err != nil {
+			return nil, err
+		}
+		r.Path, err = filepath.Abs(r.Path)
+		if err != nil {
+			return nil, err
+		}
+		stat, err := os.Stat(r.Path)
+		if err != nil {
+			return nil, err
+		}
+		if !stat.IsDir() {
+			return nil, errors.New("api: shared root must be a directory")
+		}
+		cfg.Roots[name] = r
+	}
+	return cfg.Roots, nil
+}
+func sourceWithin(root, name string) (string, error) {
+	real, err := filepath.EvalSymlinks(name)
+	if err != nil {
+		return "", err
+	}
+	rel, err := filepath.Rel(root, real)
+	if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+		return "", errors.New("api: imports must stay within their declared contract root")
+	}
+	return filepath.ToSlash(rel), nil
+}
+func sharedHash(sources map[string][]byte, alias string) string {
+	values := map[string]string{}
+	for name, data := range sources {
+		if strings.HasPrefix(name, "@"+alias+"/") {
+			values[strings.TrimPrefix(name, "@"+alias+"/")] = digest(data)
+		}
+	}
+	raw, _ := json.Marshal(values)
+	return digest(raw)
+}
+func sourceMetadata(spec *Spec) map[string]any {
+	hashes := map[string]string{}
+	for name, data := range spec.Sources {
+		hashes[name] = digest(data)
+	}
+	shared := map[string]any{}
+	for alias, r := range spec.SharedRoots {
+		shared[alias] = map[string]string{"version": r.Version, "sha256": sharedHash(spec.Sources, alias)}
+	}
+	return map[string]any{"files": hashes, "shared": shared}
+}
+func sharedSeeds(spec *Spec, directory string) ([]byte, error) {
+	cfg := sharedConfig{Roots: map[string]SharedRoot{}}
+	for name, r := range spec.SharedRoots {
+		rel, err := filepath.Rel(filepath.Join(directory, "api"), r.Path)
+		if err != nil {
+			return nil, err
+		}
+		r.Path = filepath.ToSlash(rel)
+		cfg.Roots[name] = r
+	}
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	return append(data, '\n'), err
+}
+func validateSharedPins(spec *Spec) error {
+	names := make([]string, 0, len(spec.SharedRoots))
+	for name := range spec.SharedRoots {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	for _, name := range names {
+		r := spec.SharedRoots[name]
+		if r.SHA256 != "" && r.SHA256 != sharedHash(spec.Sources, name) {
+			return fmt.Errorf("api: shared contract %s checksum differs (got %s)", name, sharedHash(spec.Sources, name))
+		}
+	}
+	return nil
+}
--- a/cmd/go-omni/apigen/shared_test.go
+++ b/cmd/go-omni/apigen/shared_test.go
@@ -0,0 +1,96 @@
+package apigen
+
+import (
+	"bytes"
+	"encoding/json"
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestControlledSharedContracts(t *testing.T) {
+	root := t.TempDir()
+	shared := filepath.Join(root, "shared")
+	writeFile(t, filepath.Join(shared, "response.api"), "response Common (codeType: int32; successCode: 0; errorCode: 9999; dataMode: always)\ntype Item { Name string `json:\"name\"` }\n")
+	for _, service := range []string{"api", "id"} {
+		dir := filepath.Join(root, service)
+		entry := filepath.Join(dir, "api/service.api")
+		writeFile(t, entry, "import \"@common/response.api\"\n@app(defaultResponse: Common)\nservice demo {\n@handler get\nget /get returns (Item)\n}\n")
+		config := `{"roots":{"common":{"path":"../../shared","version":"1.0.0"}}}`
+		writeFile(t, filepath.Join(dir, "api/omni.imports.json"), config)
+		spec, err := Parse(entry)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if len(spec.Sources) != 2 || len(spec.SourcePaths) != 2 {
+			t.Fatalf("%+v", spec)
+		}
+		pin := sharedHash(spec.Sources, "common")
+		config = strings.Replace(config, `"version":"1.0.0"`, `"version":"1.0.0","sha256":"`+pin+`"`, 1)
+		writeFile(t, filepath.Join(dir, "api/omni.imports.json"), config)
+		o := Options{Dir: dir, API: entry, Module: "example.com/" + service, FrameworkDir: frameworkRoot(t)}
+		if _, err = Generate(o); err != nil {
+			t.Fatal(err)
+		}
+		o.Check = true
+		if _, err = Generate(o); err != nil {
+			t.Fatal(err)
+		}
+		if _, err = os.Stat(filepath.Join(dir, "api/@common")); !os.IsNotExist(err) {
+			t.Fatal("shared contract copied into service")
+		}
+		document := readFile(t, filepath.Join(dir, "docs/openapi.json"))
+		if !strings.Contains(document, pin) || !strings.Contains(document, "@common/response.api") {
+			t.Fatal("missing provenance")
+		}
+		writeFile(t, filepath.Join(dir, "api/omni.imports.json"), strings.Replace(config, pin, strings.Repeat("0", 64), 1))
+		if _, err = Parse(entry); err == nil {
+			t.Fatal("checksum mismatch accepted")
+		}
+	}
+	// An undeclared alias, traversal, symlink escape and cycle are all rejected.
+	for _, imp := range []string{"@missing/response.api", "@common/../outside.api", "../shared/response.api", "@common/escape.api", "@common/cycle.api"} {
+		local := filepath.Join(root, "consumer")
+		writeFile(t, filepath.Join(local, "omni.imports.json"), `{"roots":{"common":{"path":"../shared"}}}`)
+		writeFile(t, filepath.Join(root, "outside.api"), "type Outside {}\n")
+		_ = os.Symlink(filepath.Join(root, "outside.api"), filepath.Join(shared, "escape.api"))
+		writeFile(t, filepath.Join(shared, "cycle.api"), "import \"cycle.api\"\n")
+		entry := filepath.Join(local, "service.api")
+		writeFile(t, entry, "import "+strconvQuote(imp)+"\nservice demo{\n@handler get\nget /get\n}\n")
+		if _, err := Parse(entry); err == nil {
+			t.Fatal("unsafe import accepted", imp)
+		}
+	}
+}
+func strconvQuote(value string) string { data, _ := json.Marshal(value); return string(data) }
+func TestCatalogDocumentExportDoesNotGenerateRuntimeRegistry(t *testing.T) {
+	dir := t.TempDir()
+	entry := filepath.Join(dir, "service.api")
+	writeFile(t, entry, "@app(defaultResponse: Common)\nresponse Common(codeType: int32; successCode: 0; errorCode: 9999; messageField: msg; dataMode: always)\nservice demo{\n@handler get\nget /get returns (null)\n}\n")
+	var exported bytes.Buffer
+	err := apierrors.ExportCatalog(&exported, apierrors.Catalog{DefaultStatus: 200, Definitions: map[string]apierrors.Definition{"TOO_LONG": {Code: 400002, Message: "{label}不能超过{max}个字符", Params: []apierrors.Parameter{{Name: "label", Type: "string", Example: "企业名称"}, {Name: "max", Type: "int", Example: 100}}}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	writeFile(t, filepath.Join(dir, "omni.errors.json"), exported.String())
+	spec, err := Parse(entry)
+	if err != nil {
+		t.Fatal(err)
+	}
+	c, err := Compile(spec)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(c.Spec.Errors) != 0 || !strings.Contains(string(c.Document), "企业名称不能超过100个字符") {
+		t.Fatal(string(c.Document))
+	}
+	target := filepath.Join(t.TempDir(), "catalog")
+	if _, err = Generate(Options{Dir: target, API: entry, Module: "example.com/catalog", FrameworkDir: frameworkRoot(t)}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = os.Stat(filepath.Join(target, "internal/apierrors/errorsGen.go")); !os.IsNotExist(err) {
+		t.Fatal("document metadata became a runtime error registry")
+	}
+}
--- a/cmd/go-omni/apigen/startup.go
+++ b/cmd/go-omni/apigen/startup.go
@@ -20,8 +20,11 @@ import (
 func NewApp(deps *svc.ServiceContext)(*omni.App,error){
 if deps==nil || deps.Lifecycle==nil{return nil,fmt.Errorf("service context and lifecycle controller required; see PROJECT.md upgrade instructions")}
 cfg:=deps.Config.Server
+ cfg.LogInstance=deps.Logger
 for _,option:=range deps.AppOptions(){if option!=nil{option(&cfg)}}
 `, frameworkModule, frameworkModule+"/httpx", frameworkModule+"/config", frameworkModule+"/health", o.Module+"/internal/svc")
+	source += fmt.Sprintf("cfg.Request=contract.MergePolicy(cfg.Request,%#v)\n", spec.RequestPolicy)
+	source = strings.Replace(source, "\"fmt\"", "\"fmt\";"+fmt.Sprintf("%q", frameworkModule+"/contract"), 1)
 	if spec.DefaultResponse != "" {
 		for _, r := range spec.Responses {
 			if r.Name == spec.DefaultResponse {
--- a/cmd/go-omni/apigen/templates.go
+++ b/cmd/go-omni/apigen/templates.go
@@ -28,14 +28,10 @@ func run(ctx context.Context,path string)(runErr error){
 cfg,err:=config.Load(path);if err!=nil{return err}
 logger,err:=logx.New(cfg.Server.Log);if err!=nil{return err}
 defer func(){runErr=errors.Join(runErr,logger.Close())}()
- logx.SetDefault(logger)
 deps,err:=svc.New(ctx,logger,cfg);if err!=nil{return err}
 // RunContext drains HTTP requests before returning. This scope owns dependencies
 // and closes them exactly once, before closing the borrowed logger.
- defer func(){
-  runErr=errors.Join(runErr,deps.Close())
-  if cause:=deps.Lifecycle.Err();cause!=nil && !errors.Is(runErr,cause){runErr=errors.Join(runErr,cause)}
- }()
+ defer func(){runErr=deps.Finish(runErr)}()
 app,err:=handler.NewApp(deps);if err!=nil{return err}
 defer func(){runErr=errors.Join(runErr,app.Close())}()
 logger.InfoContext(ctx,"service.starting","address",app.Config().Address)
@@ -111,6 +107,16 @@ and produce REVIEW notices. This source scan does not execute project code or
 replace go test ./... . Snapshot-based REVIEW notices describe changes since the
 last successful generation; they do not persist as an acknowledgement checklist.

+## Contract tools
+
+api format [--check] preserves comments and normalizes indentation. api upgrade
+previews changed infrastructure; --apply only replaces recognized prior seeds.
+Use @request policy overrides and @app(request: {...}) for query/JSON strictness.
+Explicitly exported api/omni.errors.json documents the Go-owned error catalog;
+the CLI never executes project Go. omni.imports.json permits named shared roots;
+workspace format/generate/check processes explicitly listed independent services.
+Full reference: https://git.yuntuo.hk/k2safe/go-omni/src/branch/main/DEVELOPMENT.md
+
 ## Layout

 `+"```text"+`
@@ -119,7 +125,8 @@ main.go                      # GENERATED startup, lifecycle and route registrati
 etc/config.yaml              # lowerCamelCase configuration
 internal/config/             # defaults -> file -> environment
 internal/svc/                # dependency initialization and cleanup
-internal/types/typesGen.go    # generated request/response types
+internal/types/*Gen.go        # DTOs split by source API, one types package
+internal/svc/runtimeGen.go    # GENERATED lifecycle and infrastructure startup
 internal/apierrors/errorsGen.go # generated fresh error constructors, when declared
 internal/handler/<group>/     # generated binding and Logic adapters
 internal/logic/<group>/      # developer-owned business operations
@@ -138,7 +145,7 @@ use the same contract. 404/405 and ordinary App routes use the declared App defa
 No template is selected by declaration/import order. Without @app, existing framework
 response defaults apply. An explicit API App default takes precedence over response
 options in svc, keeping generated routes and OpenAPI consistent.
-Handlers reject nil successful responses. Body DTOs use application/json and have a 1 MiB limit by default.
+Object responses reject nil; []DTO maps nil to []; *DTO permits null; returns(null) is a successful null value. No returns means 204. Body DTOs use application/json and have a 1 MiB limit by default.
 Use @body(maxBytes: ...) for route limits. @body(mode: raw|multipart; maxBytes: ...)
 adds a *httpx.Body argument to Logic, without handwritten handlers. Raw is the exact
 limited request stream; Parts supports sequential multipart reading with no temp files.
@@ -146,11 +153,10 @@ limited request stream; Parts supports sequential multipart reading with no temp
 Logic result of *httpx.Stream; the handler closes Content and streams it unwrapped.
 Signature verification and storage policy belong to Logic/middleware. A consumed
 request stream cannot be reread automatically; use one reader owner or explicitly
-bounded buffering. Stream reads respect configured server timeouts. Multipart parts
-are not DTO form fields: form tags remain URL query parameters. The optional manual
+bounded buffering. Stream reads respect configured server timeouts. Declare multipart/multipartJSON/file DTO fields for validated uploads; without those fields the existing streaming Body is passed. form tags remain URL query parameters. The optional manual
 handler/custom binder hooks are preserved, and are needed only for custom protocols.

-Fields require exactly one source tag: json, path, form (URL query only), header.
+Fields require one source tag: json, path, form (URL query), header, multipart, multipartJSON or file. Multipart fields select full automatic binding before Logic; File/[]File are request-scoped disk-backed uploads. Use File.Open to stream them; generated cleanup owns their lifetime.
 All are required by presence unless optional, omitempty or default is specified.
 Zero and false are valid present values; binding:"required" rejects scalar zero.
 Use *T with optional when business logic needs to distinguish missing from zero.
@@ -171,7 +177,7 @@ The selected auth runs first; @auth none removes inherited declarative auth.
 Validation policy remains in the middleware implementation. Public messages must
 not contain secrets; error causes may be included in server logs.

-svc.New receives the loaded Config and borrowed Logger. Add dependencies there,
+Generated svc.New receives Config and a borrowed Logger. Add dependencies in svc.Init,
 then immediately register each cleanup with OnClose. A later initialization failure
 runs registered cleanups in reverse order. Close is idempotent. GlobalMiddleware
 provides global hooks; Middlewares supplies named API hooks. AppOptions is evaluated
@@ -208,7 +214,7 @@ func infrastructureREADME(o Options) string {

 Selected database: %s; storage: %s; logging: %s/%s.
 MySQL uses database/sql through deps.DB, including InTx and a readiness probe.
-Set GO_OMNI_DB_DSN; pool settings live in etc/config.yaml and GO_OMNI_DB_*.
+Use structured database/mysql configuration and GO_OMNI_DB_PASSWORD. Other connection/pool/TLS settings live in etc/config.yaml and GO_OMNI_DB_*.
 No tables are invented or migrated automatically from request/response DTOs.
 The none/memory selection opens no database; implement repositories per business.

--- a/cmd/go-omni/apigen/testdata/business/accessFactory.go
+++ b/cmd/go-omni/apigen/testdata/business/accessFactory.go
@@ -0,0 +1,22 @@
+package middleware
+
+import (
+	"context"
+	"git.yuntuo.hk/k2safe/go-omni/httpx"
+)
+
+// This package deliberately imports no svc; the dependency is supplied explicitly.
+type AccessChecker interface {
+	CheckAccess(context.Context, string) error
+}
+
+func NewRequireAccess(checker AccessChecker) httpx.Middleware {
+	return func(next httpx.Handler) httpx.Handler {
+		return func(c *httpx.Context) error {
+			if err := checker.CheckAccess(c.Context(), c.Header("Authorization")); err != nil {
+				return err
+			}
+			return next(c)
+		}
+	}
+}
--- a/cmd/go-omni/apigen/testdata/business/client.go
+++ b/cmd/go-omni/apigen/testdata/business/client.go
@@ -0,0 +1,32 @@
+package svc
+
+import (
+	"context"
+	"example.com/business/internal/middleware"
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"git.yuntuo.hk/k2safe/go-omni/httpx"
+	"sync/atomic"
+)
+
+// A local fixture checks wiring; production authentication is project-owned.
+type accessClient struct{ closed atomic.Bool }
+
+func (c *accessClient) Close() error { c.closed.Store(true); return nil }
+func (c *accessClient) CheckAccess(ctx context.Context, token string) error {
+	if c.closed.Load() {
+		return apierrors.New(503, "CLOSED", "closed")
+	}
+	if httpx.Metadata(ctx).Route == "" {
+		return apierrors.New(500, "NO_METADATA", "missing route")
+	}
+	if token == "reject" {
+		return apierrors.New(403, "DENIED", "denied")
+	}
+	return nil
+}
+func (c *ServiceContext) initAccess(ctx context.Context) error {
+	c.Client = &accessClient{}
+	c.OnClose(c.Client.Close)
+	c.Middlewares["RequireAccess"] = middleware.NewRequireAccess(c.Client)
+	return nil
+}
--- a/cmd/go-omni/apigen/testdata/business/consumer_test.go
+++ b/cmd/go-omni/apigen/testdata/business/consumer_test.go
@@ -0,0 +1,119 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"example.com/business/internal/config"
+	"example.com/business/internal/handler"
+	"example.com/business/internal/svc"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+	"io"
+	"mime/multipart"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestShapesAndPolicy(t *testing.T) {
+	cfg := config.Default()
+	cfg.Server.Log.Writer = io.Discard
+	logger, err := logx.New(cfg.Server.Log)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logger.Close()
+	deps, err := svc.New(context.Background(), logger, cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer deps.Close()
+	app, err := handler.NewApp(deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer app.Close()
+	for _, tt := range []struct {
+		method, path, body, media string
+		status                    int
+		data                      string
+		raw                       bool
+	}{
+		{"GET", "/list", "", "", 200, `[]`, false},
+		{"GET", "/list?mode=full&tags=a&tags=b", "", "", 200, `[{"name":"one"}]`, false},
+		{"GET", "/nullable", "", "", 200, `null`, false},
+		{"GET", "/nullable?mode=full", "", "", 200, `{"name":"one"}`, false},
+		{"POST", "/nothing", "", "", 200, `null`, false},
+		{"GET", "/rawNull", "", "", 200, `null`, true},
+		{"GET", "/rawArray", "", "", 200, `[]`, true},
+		{"DELETE", "/noContent", "", "", 204, "", true},
+		{"POST", "/empty", `{}`, "application/json", 200, `null`, false},
+		{"POST", "/empty", ``, "application/json", 400, "", false},
+		{"POST", "/empty", `{"unknown":1}`, "application/json", 400, "", false},
+		{"POST", "/absent", ``, "", 200, `null`, false},
+		{"POST", "/absent", `{}`, "application/json", 400, "", false},
+		{"POST", "/optional", ``, "", 200, `{"name":""}`, false},
+		{"POST", "/optional", `{}`, "application/json", 400, "", false},
+		{"POST", "/echo", `{"name":"ok"}`, "application/json", 200, `{"name":"ok"}`, false},
+		{"POST", "/echo", `{"name":"ok"}`, "application/json; charset=latin1", 415, "", false},
+		{"POST", "/echo", "{\"name\":\"\xff\"}", "application/json", 400, "", false},
+		{"GET", "/list?unknown=1", "", "", 400, "", false},
+		{"GET", "/rawNull?unknown=1", "", "", 400, "", false},
+		{"POST", "/tolerant?unknown=1", "{\"name\":\"\xff\"}", "application/json; charset=latin1", 200, `{"name":"<22>"}`, false},
+	} {
+		t.Run(tt.method+tt.path+tt.body+tt.media, func(t *testing.T) {
+			r := httptest.NewRequest(tt.method, tt.path, strings.NewReader(tt.body))
+			if tt.media != "" {
+				r.Header.Set("Content-Type", tt.media)
+			}
+			w := httptest.NewRecorder()
+			app.ServeHTTP(w, r)
+			if w.Code != tt.status {
+				t.Fatalf("%d %s", w.Code, w.Body)
+			}
+			if tt.status >= 400 {
+				return
+			}
+			data := strings.TrimSpace(w.Body.String())
+			if !tt.raw {
+				var obj map[string]json.RawMessage
+				if err := json.Unmarshal(w.Body.Bytes(), &obj); err != nil {
+					t.Fatal(err)
+				}
+				v, ok := obj["data"]
+				if !ok {
+					t.Fatal("missing data")
+				}
+				data = string(v)
+			}
+			if data != tt.data {
+				t.Fatalf("data %s expected %s", data, tt.data)
+			}
+		})
+	}
+	var body bytes.Buffer
+	form := multipart.NewWriter(&body)
+	_ = form.WriteField("title", "title")
+	_ = form.WriteField("metadata", `{"name":"meta"}`)
+	f, err := form.CreateFormFile("attachment", "a.txt")
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, _ = io.WriteString(f, "content")
+	_ = form.Close()
+	r := httptest.NewRequest("POST", "/upload", &body)
+	r.Header.Set("Content-Type", form.FormDataContentType())
+	w := httptest.NewRecorder()
+	app.ServeHTTP(w, r)
+	if w.Code != 200 || !strings.Contains(w.Body.String(), "title:meta:content") {
+		t.Fatal(w.Code, w.Body.String())
+	}
+	denied := httptest.NewRequest("GET", "/list", nil)
+	denied.Header.Set("Authorization", "reject")
+	result := httptest.NewRecorder()
+	app.ServeHTTP(result, denied)
+	if result.Code != 403 {
+		t.Fatal("injected middleware did not run", result.Code, result.Body.String())
+	}
+
+}
--- a/cmd/go-omni/apigen/testdata/business/operations.go
+++ b/cmd/go-omni/apigen/testdata/business/operations.go
@@ -0,0 +1,42 @@
+package demo
+
+import (
+	"context"
+	"example.com/business/internal/types"
+	"io"
+)
+
+func (s *Logic) List(ctx context.Context, req *types.Query) ([]types.Item, error) {
+	if req.Mode == "full" {
+		return []types.Item{{Name: "one"}}, nil
+	}
+	return nil, nil
+}
+func (s *Logic) Nullable(ctx context.Context, req *types.Query) (*types.Item, error) {
+	if req.Mode == "full" {
+		return &types.Item{Name: "one"}, nil
+	}
+	return nil, nil
+}
+func (s *Logic) Nothing(ctx context.Context) error                                  { return nil }
+func (s *Logic) RawNull(ctx context.Context) error                                  { return nil }
+func (s *Logic) RawArray(ctx context.Context) ([]types.Item, error)                 { return nil, nil }
+func (s *Logic) Empty(ctx context.Context) error                                    { return nil }
+func (s *Logic) Absent(ctx context.Context) error                                   { return nil }
+func (s *Logic) Optional(ctx context.Context, req *types.Item) (*types.Item, error) { return req, nil }
+func (s *Logic) Echo(ctx context.Context, req *types.Item) (*types.Item, error)     { return req, nil }
+func (s *Logic) Tolerant(ctx context.Context, req *types.Item) (*types.Item, error) { return req, nil }
+func (s *Logic) NoContent(ctx context.Context) error                                { return nil }
+
+func (s *Logic) Upload(ctx context.Context, req *types.Upload) (*types.Item, error) {
+	f, err := req.Attachment.Open()
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	data, err := io.ReadAll(f)
+	if err != nil {
+		return nil, err
+	}
+	return &types.Item{Name: req.Title + ":" + req.Metadata.Name + ":" + string(data)}, nil
+}
--- a/cmd/go-omni/apigen/upgrade.go
+++ b/cmd/go-omni/apigen/upgrade.go
@@ -0,0 +1,296 @@
+package apigen
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"git.yuntuo.hk/k2safe/go-omni/cmd/go-omni/scaffold"
+	"go/ast"
+	"go/format"
+	goparser "go/parser"
+	gotoken "go/token"
+	"golang.org/x/mod/modfile"
+	"golang.org/x/mod/semver"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+type UpgradeChange struct {
+	Path, Action  string
+	Manual        bool
+	before, after []byte
+	mode          os.FileMode
+	exists        bool
+}
+type UpgradePlan struct {
+	Changes       []UpgradeChange
+	Module, Entry string
+}
+
+// PlanUpgrade compares infrastructure against the exact previous release seeds.
+// A custom file is never classified as safe to replace. Logic, middleware,
+// options and repositories outside the changed templates are left untouched.
+func PlanUpgrade(dir string) (UpgradePlan, error) {
+	var plan UpgradePlan
+	root := canonical(dir)
+	if err := safePath(root, manifestPath); err != nil {
+		return plan, err
+	}
+	raw, err := os.ReadFile(filepath.Join(root, manifestPath))
+	if err != nil {
+		return plan, err
+	}
+	var m manifest
+	if err = json.Unmarshal(raw, &m); err != nil {
+		return plan, err
+	}
+	if m.Version != 2 || m.Profile == nil {
+		return plan, errors.New("upgrade requires a managed v0.13+ project")
+	}
+	if filepath.Ext(m.Entry) != ".api" {
+		return plan, errors.New("upgrade requires a valid API entry")
+	}
+	if err = safePath(root, m.Entry); err != nil {
+		return plan, err
+	}
+	plan.Module, plan.Entry = m.Module, m.Entry
+	if semver.IsValid(m.TemplateVersion) && semver.Compare(m.TemplateVersion, minimumVersion) >= 0 {
+		return plan, nil
+	}
+	p := m.Profile
+	legacy, err := scaffold.LegacyAPIInfrastructure(m.Module, p.Database, p.Storage, p.LogOutput, p.LogFormat)
+	if err != nil {
+		return plan, err
+	}
+	current, err := scaffold.APIInfrastructure(m.Module, p.Database, p.Storage, p.LogOutput, p.LogFormat)
+	if err != nil {
+		return plan, err
+	}
+	names := map[string]bool{}
+	for name := range legacy {
+		names[name] = true
+	}
+	for name := range current {
+		if !strings.HasSuffix(name, "Gen.go") {
+			names[name] = true
+		}
+	}
+	sorted := make([]string, 0, len(names))
+	for name := range names {
+		sorted = append(sorted, name)
+	}
+	sort.Strings(sorted)
+	for _, name := range sorted {
+		// options.go is unchanged by this release. Its application customizations remain untouched.
+		previous, next := legacy[name], current[name]
+		if strings.HasSuffix(name, ".go") {
+			if previous != nil {
+				previous, err = format.Source(previous)
+				if err != nil {
+					return plan, err
+				}
+			}
+			if next != nil {
+				next, err = format.Source(next)
+				if err != nil {
+					return plan, err
+				}
+			}
+		}
+		if bytes.Equal(previous, next) {
+			continue
+		}
+		if err = safePath(root, name); err != nil {
+			return plan, err
+		}
+		existing, readErr := os.ReadFile(filepath.Join(root, name))
+		if readErr != nil && !errors.Is(readErr, os.ErrNotExist) {
+			return plan, readErr
+		}
+		exists := readErr == nil
+		if bytes.Equal(existing, next) {
+			continue
+		}
+		mode := os.FileMode(0644)
+		if exists {
+			stat, e := os.Stat(filepath.Join(root, name))
+			if e != nil {
+				return plan, e
+			}
+			mode = stat.Mode().Perm()
+		}
+		action := "update"
+		if next == nil {
+			action = "remove"
+		} else if !exists {
+			action = "create"
+		}
+		plan.Changes = append(plan.Changes, UpgradeChange{Path: name, Action: action, Manual: exists && !bytes.Equal(existing, previous), before: existing, after: next, mode: mode, exists: exists})
+	}
+	if err = safePath(root, "go.mod"); err != nil {
+		return plan, err
+	}
+	raw, err = os.ReadFile(filepath.Join(root, "go.mod"))
+	if err != nil {
+		return plan, err
+	}
+	mf, err := modfile.Parse("go.mod", raw, nil)
+	if err != nil {
+		return plan, err
+	}
+	for _, r := range mf.Require {
+		if r.Mod.Path == frameworkModule && semver.Compare(r.Mod.Version, minimumVersion) < 0 {
+			if err = mf.AddRequire(frameworkModule, minimumVersion); err != nil {
+				return plan, err
+			}
+			next, e := mf.Format()
+			if e != nil {
+				return plan, e
+			}
+			stat, e := os.Stat(filepath.Join(root, "go.mod"))
+			if e != nil {
+				return plan, e
+			}
+			plan.Changes = append(plan.Changes, UpgradeChange{Path: "go.mod", Action: "update", before: raw, after: next, exists: true, mode: stat.Mode().Perm()})
+			break
+		}
+	}
+	return plan, nil
+}
+
+// PreviewUpgrade writes only proposed infrastructure files into an empty directory.
+// It never mutates the service or emits a replacement business tree.
+func PreviewUpgrade(dir, destination string) (UpgradePlan, error) {
+	plan, err := PlanUpgrade(dir)
+	if err != nil {
+		return plan, err
+	}
+	if entries, e := os.ReadDir(destination); e == nil && len(entries) > 0 {
+		return plan, errors.New("upgrade preview directory must be empty")
+	} else if e != nil && !errors.Is(e, os.ErrNotExist) {
+		return plan, e
+	}
+	for _, c := range plan.Changes {
+		if c.after == nil {
+			continue
+		}
+		if err = safePath(destination, c.Path); err != nil {
+			return plan, err
+		}
+		if err = atomicWrite(destination, c.Path, c.after, 0644); err != nil {
+			return plan, err
+		}
+	}
+	note := "# Infrastructure upgrade preview\n\nOnly untouched v0.13 seed files can be replaced automatically. Custom files require a targeted edit; this preview is never copied over the project automatically.\n\nMove dependency initialization into ServiceContext.Init; embed *lifecycle.Runtime; register cleanup with OnClose. Remove old New/Close/OnClose implementations after preserving their project work in Init or cleanup hooks. Use structured database/mysql.Config and DatabaseOptions. Preserve business configuration fields, AppOptions, middleware and Logic.\n\n"
+	for _, c := range plan.Changes {
+		note += fmt.Sprintf("- %s %s (manual review: %t)\n", c.Action, c.Path, c.Manual)
+	}
+	if err = safePath(destination, "UPGRADE.md"); err != nil {
+		return plan, err
+	}
+	return plan, atomicWrite(destination, "UPGRADE.md", []byte(note), 0644)
+}
+
+// ApplyUpgrade applies only recognized seed changes under the same generation
+// lock. A generation failure restores every changed developer file. Any manual
+// review item blocks all writes; use PreviewUpgrade and migrate that file first.
+func ApplyUpgrade(dir string) (plan UpgradePlan, err error) {
+	root := canonical(dir)
+	if err = safePath(root, ".goOmni/api.lock"); err != nil {
+		return plan, err
+	}
+	lock, err := os.OpenFile(filepath.Join(root, ".goOmni/api.lock"), os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0600)
+	if err != nil {
+		return plan, err
+	}
+	_ = lock.Close()
+	defer os.Remove(filepath.Join(root, ".goOmni/api.lock"))
+	plan, err = PlanUpgrade(root)
+	if err != nil {
+		return plan, err
+	}
+	for _, c := range plan.Changes {
+		if c.Manual {
+			return plan, fmt.Errorf("upgrade: %s contains project changes; inspect an upgrade preview and migrate it explicitly", c.Path)
+		}
+	}
+	var changed []UpgradeChange
+	defer func() {
+		if err != nil {
+			for i := len(changed) - 1; i >= 0; i-- {
+				c := changed[i]
+				if c.exists {
+					err = errors.Join(err, atomicWrite(root, c.Path, c.before, c.mode))
+				} else {
+					e := os.Remove(filepath.Join(root, c.Path))
+					if !errors.Is(e, os.ErrNotExist) {
+						err = errors.Join(err, e)
+					}
+				}
+			}
+		}
+	}()
+	for _, c := range plan.Changes {
+		if c.after == nil {
+			err = os.Remove(filepath.Join(root, c.Path))
+		} else {
+			err = atomicWrite(root, c.Path, c.after, c.mode)
+		}
+		if err != nil {
+			return plan, err
+		}
+		changed = append(changed, c)
+	}
+	preview, e := Generate(Options{Dir: root, API: filepath.Join(root, plan.Entry), DryRun: true, lockHeld: true})
+	if e != nil {
+		return plan, e
+	}
+	if diagnosticErrors(preview.Diagnostics) > 0 {
+		return plan, errors.New("upgrade: Logic checks failed; resolve diagnostics before applying")
+	}
+	_, err = Generate(Options{Dir: root, API: filepath.Join(root, plan.Entry), lockHeld: true})
+	return plan, err
+}
+
+func checkRuntimeExtension(root string) error {
+	directory := filepath.Join(root, "internal/svc")
+	files, err := os.ReadDir(directory)
+	if errors.Is(err, os.ErrNotExist) {
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	for _, entry := range files {
+		if !sourceFile(entry.Name()) || strings.HasSuffix(entry.Name(), "Gen.go") {
+			continue
+		}
+		path := filepath.Join(directory, entry.Name())
+		file, err := goparser.ParseFile(gotoken.NewFileSet(), path, nil, goparser.SkipObjectResolution)
+		if err != nil {
+			return err
+		}
+		for _, decl := range file.Decls {
+			fn, ok := decl.(*ast.FuncDecl)
+			if !ok {
+				continue
+			}
+			if fn.Recv == nil && fn.Name.Name == "New" {
+				return fmt.Errorf("%s owns New; run go-omni api upgrade --dir %s and move project initialization into ServiceContext.Init", path, root)
+			}
+			if fn.Recv != nil && (fn.Name.Name == "Close" || fn.Name.Name == "OnClose" || fn.Name.Name == "Finish") {
+				receiver := fn.Recv.List[0].Type
+				if p, ok := receiver.(*ast.StarExpr); ok {
+					receiver = p.X
+				}
+				if id, ok := receiver.(*ast.Ident); ok && id.Name == "ServiceContext" {
+					return fmt.Errorf("%s overrides framework resource lifecycle; inspect go-omni api upgrade and register cleanup in Init", path)
+				}
+			}
+		}
+	}
+	return nil
+}
--- a/cmd/go-omni/apigen/upgrade_test.go
+++ b/cmd/go-omni/apigen/upgrade_test.go
@@ -0,0 +1,124 @@
+package apigen
+
+import (
+	"encoding/json"
+	"git.yuntuo.hk/k2safe/go-omni/cmd/go-omni/scaffold"
+	"go/format"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func oldInfrastructureProject(t *testing.T) string {
+	t.Helper()
+	dir := filepath.Join(t.TempDir(), "app")
+	if _, err := New(Options{Dir: dir, Module: "example.com/upgrade", FrameworkDir: frameworkRoot(t)}); err != nil {
+		t.Fatal(err)
+	}
+	previous, err := scaffold.LegacyAPIInfrastructure("example.com/upgrade", "none", "none", "stderr", "json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for name, content := range previous {
+		if strings.HasSuffix(name, ".go") {
+			content, err = format.Source(content)
+			if err != nil {
+				t.Fatal(err)
+			}
+		}
+		writeFile(t, filepath.Join(dir, name), string(content))
+	}
+	var m manifest
+	if err = json.Unmarshal([]byte(readFile(t, filepath.Join(dir, manifestPath))), &m); err != nil {
+		t.Fatal(err)
+	}
+	delete(m.Generated, "internal/svc/runtimeGen.go")
+	m.TemplateVersion = ""
+	_ = os.Remove(filepath.Join(dir, "internal/svc/runtimeGen.go"))
+	raw, _ := json.Marshal(m)
+	writeFile(t, filepath.Join(dir, manifestPath), string(raw))
+	path := filepath.Join(dir, "go.mod")
+	writeFile(t, path, strings.ReplaceAll(readFile(t, path), minimumVersion, "v0.13.0-preview"))
+	return dir
+}
+
+func TestUpgradeRejectsEscapingEntry(t *testing.T) {
+	dir := oldInfrastructureProject(t)
+	var m manifest
+	if err := json.Unmarshal([]byte(readFile(t, filepath.Join(dir, manifestPath))), &m); err != nil {
+		t.Fatal(err)
+	}
+	m.Entry = "../outside.api"
+	raw, _ := json.Marshal(m)
+	writeFile(t, filepath.Join(dir, manifestPath), string(raw))
+	before := snapshot(t, dir)
+	if _, err := ApplyUpgrade(dir); err == nil {
+		t.Fatal("escaping API entry accepted")
+	}
+	if !sameFiles(before, snapshot(t, dir)) {
+		t.Fatal("invalid upgrade wrote project")
+	}
+}
+func TestSafeInfrastructureUpgrade(t *testing.T) {
+	dir := oldInfrastructureProject(t)
+	before := snapshot(t, dir)
+	if _, err := Generate(Options{Dir: dir, API: filepath.Join(dir, "api/service.api")}); err == nil {
+		t.Fatal("legacy constructor accepted")
+	}
+	if !sameFiles(before, snapshot(t, dir)) {
+		t.Fatal("failed generate wrote files")
+	}
+	plan, err := PlanUpgrade(dir)
+	if err != nil || len(plan.Changes) == 0 {
+		t.Fatal(plan, err)
+	}
+	for _, c := range plan.Changes {
+		if c.Manual {
+			t.Fatal(c.Path)
+		}
+	}
+	preview := filepath.Join(t.TempDir(), "preview")
+	if _, err = PreviewUpgrade(dir, preview); err != nil {
+		t.Fatal(err)
+	}
+	if !sameFiles(before, snapshot(t, dir)) {
+		t.Fatal("preview changed project")
+	}
+	logic := readFile(t, filepath.Join(dir, "internal/logic/greet/greet.go"))
+	if _, err = ApplyUpgrade(dir); err != nil {
+		t.Fatal(err)
+	}
+	if _, err = os.Stat(filepath.Join(dir, "internal/svc/close.go")); !os.IsNotExist(err) {
+		t.Fatal("old lifecycle remains")
+	}
+	if readFile(t, filepath.Join(dir, "internal/logic/greet/greet.go")) != logic {
+		t.Fatal("business changed")
+	}
+	if _, err = Generate(Options{Dir: dir, API: filepath.Join(dir, "api/service.api"), Check: true}); err != nil {
+		t.Fatal(err)
+	}
+	plan, err = PlanUpgrade(dir)
+	if err != nil || len(plan.Changes) != 0 {
+		t.Fatal("upgrade not idempotent", plan, err)
+	}
+}
+func TestUpgradePreservesCustomFilesAndRollsBack(t *testing.T) {
+	for _, custom := range []bool{true, false} {
+		dir := oldInfrastructureProject(t)
+		if custom {
+			path := filepath.Join(dir, "internal/svc/serviceContext.go")
+			writeFile(t, path, readFile(t, path)+"\n// custom dependency\n")
+		} else {
+			path := filepath.Join(dir, "internal/logic/greet/greet.go")
+			writeFile(t, path, "package greet;func(s *Logic)Greet(){}")
+		}
+		before := snapshot(t, dir)
+		if _, err := ApplyUpgrade(dir); err == nil {
+			t.Fatal("unsafe upgrade accepted")
+		}
+		if !sameFiles(before, snapshot(t, dir)) {
+			t.Fatal("failed upgrade changed project")
+		}
+	}
+}
--- a/cmd/go-omni/apigen/workspace.go
+++ b/cmd/go-omni/apigen/workspace.go
@@ -0,0 +1,126 @@
+package apigen
+
+import (
+	"errors"
+	"fmt"
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+type WorkspaceService struct {
+	Dir    string `json:"dir"`
+	API    string `json:"api,omitempty"`
+	Module string `json:"module,omitempty"`
+}
+type WorkspaceConfig struct {
+	Services []WorkspaceService `json:"services"`
+}
+
+// Workspace operates independent Go modules listed in an explicit local file.
+// All projects are preflighted before generate/format writes. Each generator
+// transaction is atomic within its project; no cross-module transaction is promised.
+func Workspace(path, command string, w io.Writer) error {
+	if command != "generate" && command != "check" && command != "format" {
+		return errors.New("workspace command must be generate, check or format")
+	}
+	if w == nil {
+		w = io.Discard
+	}
+	real, err := filepath.Abs(path)
+	if err != nil {
+		return err
+	}
+	stat, err := os.Lstat(real)
+	if err != nil {
+		return err
+	}
+	if !stat.Mode().IsRegular() || stat.Size() > 65536 {
+		return errors.New("workspace configuration must be a regular file of at most 64 KiB")
+	}
+	raw, err := os.ReadFile(real)
+	if err != nil {
+		return err
+	}
+	var cfg WorkspaceConfig
+	if err = apierrors.DecodeCatalogJSON(raw, &cfg); err != nil {
+		return err
+	}
+	if len(cfg.Services) == 0 || len(cfg.Services) > 64 {
+		return errors.New("workspace must list 1..64 services")
+	}
+	root := canonical(filepath.Dir(real))
+	var options []Options
+	seen := map[string]bool{}
+	for _, service := range cfg.Services {
+		if service.Dir == "" || service.Dir == "." {
+			return errors.New("workspace requires distinct relative service directories")
+		}
+		if err = safePath(root, service.Dir+"/.goOmniWorkspaceCheck"); err != nil {
+			return err
+		}
+		dir := filepath.Join(root, filepath.FromSlash(service.Dir))
+		key := strings.ToLower(dir)
+		for prior := range seen {
+			if prior == key || strings.HasPrefix(key, prior+string(filepath.Separator)) || strings.HasPrefix(prior, key+string(filepath.Separator)) {
+				return errors.New("workspace service directories overlap")
+			}
+		}
+		seen[key] = true
+		entry := service.API
+		if entry == "" {
+			entry, err = ProjectEntry(dir)
+		} else {
+			if err = safePath(dir, entry); err != nil {
+				return err
+			}
+			entry = filepath.Join(dir, entry)
+		}
+		if err != nil {
+			return err
+		}
+		options = append(options, Options{API: entry, Dir: dir, Module: service.Module, DryRun: true})
+	}
+	var failures error
+	for _, o := range options {
+		if command == "format" {
+			spec, e := Parse(o.API)
+			if e == nil {
+				_, e = Compile(spec)
+			}
+			err = e
+		} else {
+			_, err = Generate(o)
+		}
+		if err != nil {
+			failures = errors.Join(failures, fmt.Errorf("%s: %w", o.Dir, err))
+		}
+	}
+	if failures != nil {
+		return failures
+	}
+	for _, o := range options {
+		switch command {
+		case "format":
+			_, err = FormatProject(o.API, false)
+		case "generate":
+			o.DryRun = false
+			_, err = Generate(o)
+		case "check":
+			_, fmtErr := FormatProject(o.API, true)
+			o.DryRun = false
+			o.Check = true
+			_, genErr := Generate(o)
+			err = errors.Join(fmtErr, genErr)
+		}
+		if err != nil {
+			failures = errors.Join(failures, fmt.Errorf("%s: %w", o.Dir, err))
+			fmt.Fprintf(w, "FAIL %s\n", o.Dir)
+		} else {
+			fmt.Fprintf(w, "OK   %s\n", o.Dir)
+		}
+	}
+	return failures
+}
--- a/cmd/go-omni/apigen/workspace_test.go
+++ b/cmd/go-omni/apigen/workspace_test.go
@@ -0,0 +1,43 @@
+package apigen
+
+import (
+	"io"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestWorkspaceIndependentModules(t *testing.T) {
+	root := t.TempDir()
+	for _, name := range []string{"api", "id"} {
+		dir := filepath.Join(root, "services", name)
+		if _, err := New(Options{Dir: dir, Module: "example.com/" + name, FrameworkDir: frameworkRoot(t)}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	config := filepath.Join(root, "omni.workspace.json")
+	writeFile(t, config, `{"services":[{"dir":"services/api"},{"dir":"services/id"}]}`)
+	for _, op := range []string{"format", "generate", "check", "generate", "check"} {
+		if err := Workspace(config, op, io.Discard); err != nil {
+			t.Fatal(op, err)
+		}
+	}
+	// A bad second service must not leave the first service partially regenerated.
+	first := filepath.Join(root, "services/api/api/service.api")
+	writeFile(t, first, strings.Replace(readFile(t, first), "Greet a visitor", "Greet", 1))
+	second := filepath.Join(root, "services/id/api/service.api")
+	writeFile(t, second, "invalid source")
+	before := snapshot(t, root)
+	if err := Workspace(config, "generate", io.Discard); err == nil {
+		t.Fatal("invalid workspace accepted")
+	}
+	if !sameFiles(before, snapshot(t, root)) {
+		t.Fatal("preflight failure changed project")
+	}
+	for _, bad := range []string{`{"services":[{"dir":"../outside"}]}`, `{"services":[{"dir":"services/api"},{"dir":"services/api/nested"}]}`, `{"services":[{"dir":"services/api","dir":"services/id"}]}`} {
+		writeFile(t, config, bad)
+		if err := Workspace(config, "check", io.Discard); err == nil {
+			t.Fatal("invalid workspace accepted")
+		}
+	}
+}
--- a/cmd/go-omni/apigen/write.go
+++ b/cmd/go-omni/apigen/write.go
@@ -16,12 +16,13 @@ import (
 const manifestPath = ".goOmni/apiManifest.json"

 type manifest struct {
-	Profile   *projectProfile   `json:"profile,omitempty"`
-	Version   int               `json:"version"`
-	Module    string            `json:"module"`
-	Entry     string            `json:"entry"`
-	Generated map[string]string `json:"generated"`
-	Contract  *contractSnapshot `json:"contract,omitempty"`
+	TemplateVersion string            `json:"templateVersion,omitempty"`
+	Profile         *projectProfile   `json:"profile,omitempty"`
+	Version         int               `json:"version"`
+	Module          string            `json:"module"`
+	Entry           string            `json:"entry"`
+	Generated       map[string]string `json:"generated"`
+	Contract        *contractSnapshot `json:"contract,omitempty"`
 }
 type change struct {
 	name            string
@@ -30,7 +31,7 @@ type change struct {
 	mode            os.FileMode
 }

-func apply(root, module, entry string, generated, seeds map[string][]byte, check, dryRun bool, profile projectProfile, contract *contractSnapshot) (Output, error) {
+func apply(root, module, entry string, generated, seeds map[string][]byte, check, dryRun bool, profile projectProfile, contract *contractSnapshot, lockHeld ...bool) (Output, error) {
 	var result Output
 	if info, err := os.Lstat(root); err == nil {
 		if info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {
@@ -61,7 +62,7 @@ func apply(root, module, entry string, generated, seeds map[string][]byte, check
 	if err := safePath(root, manifestPath); err != nil {
 		return result, err
 	}
-	if !check && !dryRun {
+	if !check && !dryRun && !(len(lockHeld) > 0 && lockHeld[0]) {
 		if err := os.MkdirAll(filepath.Join(root, ".goOmni"), 0755); err != nil {
 			return result, err
 		}
@@ -108,7 +109,7 @@ func apply(root, module, entry string, generated, seeds map[string][]byte, check
 			return result, err
 		}
 	}
-	next := manifest{Profile: &profile, Version: 2, Module: module, Entry: entry, Generated: map[string]string{}, Contract: contract}
+	next := manifest{TemplateVersion: minimumVersion, Profile: &profile, Version: 2, Module: module, Entry: entry, Generated: map[string]string{}, Contract: contract}
 	for name, data := range generated {
 		next.Generated[name] = digest(data)
 	}
@@ -271,7 +272,10 @@ func apply(root, module, entry string, generated, seeds map[string][]byte, check
 }
 func digest(data []byte) string { sum := sha256.Sum256(data); return hex.EncodeToString(sum[:]) }
 func ownedPath(name string) bool {
-	if name == "main.go" || name == "internal/handler/appGen.go" || name == "internal/handler/responseGen.go" || name == "internal/types/scalarsGen.go" {
+	if strings.HasPrefix(name, "internal/types/dto") && strings.HasSuffix(name, "Gen.go") && goName.MatchString(strings.TrimSuffix(filepath.Base(name), ".go")) {
+		return true
+	}
+	if name == "main.go" || name == "internal/svc/runtimeGen.go" || name == "internal/handler/appGen.go" || name == "internal/handler/responseGen.go" || name == "internal/types/scalarsGen.go" {
 		return true
 	}
 	if name == "internal/apierrors/errorsGen.go" || name == "docs/openapi.json" || name == "internal/types/typesGen.go" || name == "internal/handler/routesGen.go" || name == "internal/handler/openapiGen.go" || name == "internal/middleware/registryGen.go" {
--- a/cmd/go-omni/main.go
+++ b/cmd/go-omni/main.go
@@ -18,6 +18,11 @@ func main() {
 	}

 	switch os.Args[1] {
+	case "workspace":
+		if err := runWorkspace(os.Args[2:]); err != nil {
+			fmt.Fprintln(os.Stderr, "go-omni workspace:", err)
+			os.Exit(1)
+		}
 	case "api":
 		if err := runAPI(os.Args[2:]); err != nil {
 			fmt.Fprintln(os.Stderr, "go-omni api:", err)
@@ -170,6 +175,9 @@ func usage() {
 	fmt.Fprintln(os.Stderr, "  go-omni new --api <file.api> [--module <module>] <directory>")
 	fmt.Fprintln(os.Stderr, "  go-omni api new [--module <module>] <directory>  Create a runnable API project")
 	fmt.Fprintln(os.Stderr, "  go-omni api generate [--api <file.api>] [--dir <project>] [--check|--dry-run]")
+	fmt.Fprintln(os.Stderr, "  go-omni api format [--api <file.api>] [--check]")
+	fmt.Fprintln(os.Stderr, "  go-omni api upgrade [--dir <project>] [--dry-run|--preview <directory>|--apply]")
+	fmt.Fprintln(os.Stderr, "  go-omni workspace <format|generate|check> [--file omni.workspace.json]")
 	fmt.Fprintln(os.Stderr, "  go-omni api inspect [--api <file.api>]  Show routes, auth and business errors")
 	fmt.Fprintln(os.Stderr, "  go-omni api export [--api <file.api>]   Write OpenAPI JSON to stdout")
 	fmt.Fprintln(os.Stderr, "  go-omni api validate --api <file.api>  Validate definitions and OpenAPI")
--- a/cmd/go-omni/main_test.go
+++ b/cmd/go-omni/main_test.go
@@ -8,7 +8,7 @@ import (
 )

 func TestNewWithRemoteFrameworkVersion(t *testing.T) {
-	for _, flag := range [][]string{{"--framework-version", "v0.13.0-preview"}, {"--framework-version=v0.13.0-preview"}} {
+	for _, flag := range [][]string{{"--framework-version", "v0.14.0-preview"}, {"--framework-version=v0.14.0-preview"}} {
 		project := filepath.Join(t.TempDir(), "billing")
 		args := append([]string{"--module", "example.com/billing"}, flag...)
 		if err := runNew(append(args, project)); err != nil {
@@ -18,7 +18,7 @@ func TestNewWithRemoteFrameworkVersion(t *testing.T) {
 		if err != nil {
 			t.Fatal(err)
 		}
-		if !strings.Contains(string(content), "go-omni v0.13.0-preview") || strings.Contains(string(content), "replace ") {
+		if !strings.Contains(string(content), "go-omni v0.14.0-preview") || strings.Contains(string(content), "replace ") {
 			t.Fatalf("CLI did not pin remote dependency: %s", content)
 		}
 	}
--- a/cmd/go-omni/scaffold/apiInfrastructure.go
+++ b/cmd/go-omni/scaffold/apiInfrastructure.go
@@ -8,17 +8,37 @@ import (
 // APIInfrastructure renders shared infrastructure without inventing business
 // tables or routes. The API generator applies these as developer-owned seeds.
 func APIInfrastructure(module, database, storage, logOutput, logFormat string) (map[string][]byte, error) {
+	return apiInfrastructure(module, database, storage, logOutput, logFormat, false)
+}
+
+// LegacyAPIInfrastructure renders only the known v0.13 seed baseline for a safe upgrade.
+func LegacyAPIInfrastructure(module, database, storage, logOutput, logFormat string) (map[string][]byte, error) {
+	return apiInfrastructure(module, database, storage, logOutput, logFormat, true)
+}
+func apiInfrastructure(module, database, storage, logOutput, logFormat string, legacy bool) (map[string][]byte, error) {
 	data := templateData{Module: module, Database: database, Storage: storage, LogOutput: logOutput, LogFormat: logFormat, API: true, Modules: true}
 	files := map[string]string{
-		"internal/svc/close.go":          "templates/api-close.go.tmpl",
+		"internal/svc/runtimeGen.go":     "templates/api-runtime.go.tmpl",
 		"internal/svc/options.go":        "templates/api-options.go.tmpl",
-		"internal/config/config.go":      "templates/modules-settings.go.tmpl",
+		"internal/config/config.go":      "templates/api-config.go.tmpl",
 		"etc/config.yaml":                "templates/modules-config.yaml.tmpl",
 		"internal/svc/serviceContext.go": "templates/api-context.go.tmpl",
 	}
+	if database == "mysql" {
+		files["internal/svc/databaseOptions.go"] = "templates/api-databaseOptions.go.tmpl"
+	}
 	if storage != "none" {
 		files["internal/svc/storage.go"] = "templates/modules-storage.go.tmpl"
 	}
+	if legacy {
+		delete(files, "internal/svc/runtimeGen.go")
+		delete(files, "internal/svc/databaseOptions.go")
+		files["internal/svc/close.go"] = "templates/api-close.go.tmpl"
+		files["internal/config/config.go"] = "templates/modules-settings.go.tmpl"
+		for name, source := range files {
+			files[name] = strings.Replace(source, "templates/", "templates/legacyV013/", 1)
+		}
+	}
 	result := make(map[string][]byte, len(files))
 	for name, source := range files {
 		content, err := render(source, data)
--- a/cmd/go-omni/scaffold/templates/api-config.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/api-config.go.tmpl
@@ -0,0 +1,104 @@
+package settings
+import (
+ "os"
+ "strings"
+ "time"
+ "git.yuntuo.hk/k2safe/go-omni/config"
+ "git.yuntuo.hk/k2safe/go-omni/logx"
+ {{if eq .Database "mysql"}}mysqladapter "git.yuntuo.hk/k2safe/go-omni/database/mysql"{{end}}
+ {{if ne .Storage "none"}}"errors"
+ {{if ne .Storage "r2"}}"net/url"{{else}}"regexp"{{end}}
+ "git.yuntuo.hk/k2safe/go-omni/storage"{{end}}
+)
+type Config struct {
+ Server config.Config `json:"server"`
+ {{if eq .Database "mysql"}}Database mysqladapter.Config `json:"database" env:"GO_OMNI_DB"`{{end}}
+ {{if ne .Storage "none"}}Storage StorageConfig `json:"storage" env:"GO_OMNI_STORAGE"`{{end}}
+}
+func Default() Config {
+ server:=config.Default()
+ server.Address="127.0.0.1:8080"
+ server.EnableLogger=true
+ server.SlowRequestThreshold=500*time.Millisecond
+ server.Log.Service={{printf "%q" .Module}}
+ server.Log.Format={{printf "%q" .LogFormat}}
+ {{if eq .LogOutput "file"}}server.Log.File="./var/log/server.log"
+ server.Log.Rotation=logx.RotationConfig{Enabled:true,MaxSizeMB:100,MaxBackups:10,MaxAgeDays:7,Compress:true}
+ {{else}}server.Log.Output={{printf "%q" .LogOutput}}{{end}}
+ return Config{Server:server{{if and .API (eq .Database "mysql")}},Database:mysqladapter.DefaultConfig(){{end}}{{if ne .Storage "none"}},Storage:StorageConfig{
+  Provider:{{printf "%q" .Storage}}, Root:"./var/files", PublicURL:"http://127.0.0.1:8080/storage/object",
+  Secure:true, MaxBytes:32<<20, ContentTypes:[]string{"text/plain","image/png","image/jpeg","application/pdf"},
+  LinkTTL:5*time.Minute, RequestTimeout:30*time.Second,
+  {{if eq .Storage "s3"}}Region:"us-east-1",{{end}}
+  {{if eq .Storage "r2"}}Region:"auto",{{end}}
+  {{if eq .Storage "oss"}}Region:"cn-hangzhou",{{end}}
+ }{{end}}}
+}
+
+// Load applies defaults -> file -> typed environment -> validation.
+// New fields automatically use GO_OMNI_<JSON_PATH>, or an explicit env tag.
+func Load(path string)(Config,error){
+ cfg:=Default();var err error
+ cfg,err=config.ApplyDefaults(cfg);if err!=nil{return Config{},err}
+ if path!="" {cfg,err=config.DecodeFile(path,cfg);if err!=nil{return Config{},err}}
+ cfg,err=config.OverlayEnv(cfg,config.EnvOptions{Prefix:"GO_OMNI_"});if err!=nil{return Config{},err}
+ // Preserve the documented framework aliases (HTTP_ADDR, LOG_LEVEL, etc).
+ cfg.Server,err=config.ApplyEnv(cfg.Server,"");if err!=nil{return Config{},err}
+ if output:=strings.TrimSpace(os.Getenv("GO_OMNI_LOG_OUTPUT"));output!="" && strings.TrimSpace(os.Getenv("GO_OMNI_LOG_FILE"))=="" {cfg.Server.Log.File="";cfg.Server.Log.Rotation=logx.RotationConfig{}}
+ return cfg,cfg.Validate()
+}
+func(c Config)Validate()error{
+ if err:=c.Server.Validate();err!=nil{return err}
+ {{if eq .Database "mysql"}}if err:=c.Database.Validate();err!=nil{return err}{{end}}
+ {{if ne .Storage "none"}}if err:=c.Storage.Validate();err!=nil{return err}{{end}}
+ return nil
+}
+{{if ne .Storage "none"}}
+type StorageConfig struct {
+ Provider string `json:"provider"`
+ Root string `json:"root"`
+ PublicURL string `json:"publicUrl"`
+ Endpoint string `json:"endpoint"`
+ Region string `json:"region"`
+ Bucket string `json:"bucket"`
+ AccountID string `json:"accountId"`
+ Secure bool `json:"secure"`
+ MaxBytes int64 `json:"maxBytes"`
+ ContentTypes []string `json:"contentTypes"`
+ LinkTTL time.Duration `json:"linkTtl"`
+ RequestTimeout time.Duration `json:"requestTimeout"`
+ // Secrets are environment-only and cannot be populated by config files.
+ FilesToken string `json:"-" env:"GO_OMNI_FILES_TOKEN,secret"`
+ SigningKey string `json:"-" env:"GO_OMNI_STORAGE_SIGNING_KEY,secret"`
+ AccessKey string `json:"-" env:"GO_OMNI_STORAGE_ACCESS_KEY,secret"`
+ SecretKey string `json:"-" env:"GO_OMNI_STORAGE_SECRET_KEY,secret"`
+ SessionToken string `json:"-" env:"GO_OMNI_STORAGE_SESSION_TOKEN,secret"`
+}
+func (s StorageConfig) Policy()storage.UploadPolicy{return storage.UploadPolicy{MaxBytes:s.MaxBytes,ContentTypes:s.ContentTypes}}
+func (s StorageConfig) Validate()error {
+ if s.Provider!={{printf "%q" .Storage}} {return errors.New("storage.provider must match the adapter selected at generation")}
+ if err:=s.Policy().Validate();err!=nil{return err}
+ if s.LinkTTL<time.Second || s.LinkTTL>time.Hour{return errors.New("storage.linkTtl must be 1s..1h")}
+ if s.RequestTimeout<=0 || s.RequestTimeout>5*time.Minute{return errors.New("storage.requestTimeout must be >0 and <=5m")}
+ {{if not .API}}if len(s.FilesToken)<32 || strings.ContainsAny(s.FilesToken," \t\r\n") {return errors.New("set GO_OMNI_FILES_TOKEN to a token of at least 32 bytes without whitespace")}{{end}}
+ {{if eq .Storage "local"}}
+ if s.Root=="" {return errors.New("storage.root is required")}
+ u,err:=url.Parse(s.PublicURL)
+ if err!=nil || u.Host=="" || u.Hostname()=="" || (u.Scheme!="http" && u.Scheme!="https") || u.User!=nil || u.RawQuery!="" || u.Fragment!="" || u.Path!="/storage/object" {return errors.New("storage.publicUrl must be an absolute HTTP(S) URL ending in /storage/object")}
+ if len(s.SigningKey)<32 {return errors.New("set GO_OMNI_STORAGE_SIGNING_KEY to a stable secret of at least 32 bytes")}
+ {{else}}
+ if s.Bucket=="" || s.Region=="" || s.AccessKey=="" || s.SecretKey=="" {return errors.New("storage bucket, region and GO_OMNI_STORAGE_ACCESS_KEY/SECRET_KEY are required")}
+ {{if eq .Storage "r2"}}
+ if !regexp.MustCompile(`^[a-fA-F0-9]{32}$`).MatchString(s.AccountID) || s.Region!="auto" || !s.Secure {return errors.New("R2 requires a 32-hex accountId, region auto and secure=true")}
+ if s.Endpoint!=""{return errors.New("this R2 profile derives endpoint from accountId; customize servicecontext for a jurisdiction-specific endpoint")}
+ {{else if eq .Storage "s3"}}
+ u,err:=url.Parse("https://"+s.Endpoint)
+ if err!=nil || s.Endpoint=="" || u.Hostname()=="" || u.User!=nil || u.Path!="" || u.RawQuery!="" || u.Fragment!="" {return errors.New("S3 endpoint must be host[:port] without scheme or path")}
+ {{else if eq .Storage "oss"}}
+ if s.Endpoint!="" {u,err:=url.Parse(s.Endpoint);if err!=nil || u.Scheme!="https" || u.Hostname()=="" || u.User!=nil || u.Path!="" || u.RawQuery!="" || u.Fragment!="" {return errors.New("OSS endpoint must be an HTTPS origin")}}
+ if !s.Secure{return errors.New("OSS requires secure=true")}
+ {{end}}
+ {{end}}
+ return nil
+}
+{{end}}
--- a/cmd/go-omni/scaffold/templates/api-context.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/api-context.go.tmpl
@@ -1,26 +1,20 @@
 package servicecontext
 import (
 "context"
- "errors"
- "sync"
 {{if ne .Storage "none"}}"net/http"
 "git.yuntuo.hk/k2safe/go-omni/storage"{{end}}
- {{if eq .Database "mysql"}}"time"
- "git.yuntuo.hk/k2safe/go-omni/database"
- "github.com/go-sql-driver/mysql"{{end}}
+ {{if eq .Database "mysql"}}"git.yuntuo.hk/k2safe/go-omni/database"{{end}}
 "git.yuntuo.hk/k2safe/go-omni/health"
 "git.yuntuo.hk/k2safe/go-omni/httpx"
 "git.yuntuo.hk/k2safe/go-omni/logx"
 "git.yuntuo.hk/k2safe/go-omni/lifecycle"
 "{{.Module}}/internal/settings"
- "{{.Module}}/internal/middleware"
 )
-// Context owns infrastructure, while Logger is borrowed from main.
-// Add business repositories here; HTTP contracts do not define database tables.
+// Context holds project dependencies. Runtime owns cleanup and shutdown.
+// Logger is borrowed; the generated entry closes it after dependencies.
 type Context struct {
- Lifecycle *lifecycle.Controller
+ *lifecycle.Runtime
 Config settings.Config
- cleanups []func()error
 Logger *logx.Logger
 Health *health.Checker
 Middlewares map[string]httpx.Middleware
@@ -31,38 +25,9 @@ type Context struct {
 Downloads storage.Presigner
 UploadLinks storage.UploadPresigner
 FileHTTP http.Handler
- storageClose func()error
 {{end}}
- closeMu sync.Mutex
- closed bool
- closeOnce sync.Once
- closeErr error
 }
-// Pass the settings loaded by main. The optional form supports lightweight
-// tests without infrastructure; selected adapters still require valid settings.
-func New(ctx context.Context,logger *logx.Logger,configs ...settings.Config)(result *Context,err error){
- if ctx==nil{ctx=context.Background()}
- if err=ctx.Err();err!=nil{return nil,errors.Join(err,lifecycle.Cause(ctx))}
- if len(configs)>1{return nil,errors.New("expected at most one configuration")}
- cfg:=settings.Default();if len(configs)==1{cfg=configs[0]}
- _=cfg
- checker,err:=health.New();if err!=nil{return nil,err}
- c:=&Context{Config:cfg,Logger:logger,Health:checker,Middlewares:middleware.Defaults(),Lifecycle:lifecycle.New(ctx)}
- ctx=c.Lifecycle.Context()
- defer func(){if err!=nil{err=errors.Join(err,c.Close());if cause:=c.Lifecycle.Err();cause!=nil && !errors.Is(err,cause){err=errors.Join(err,cause)}}}()
- {{if eq .Database "mysql"}}
- if err=cfg.Validate();err!=nil{return nil,err}
- dsn,parseErr:=mysql.ParseDSN(cfg.Database.DSN)
- if parseErr!=nil || dsn.DBName=="" {return nil,errors.New("GO_OMNI_DB_DSN must contain a valid MySQL database name")}
- dsn.ParseTime=true;dsn.Loc=time.UTC
- cfg.Database.DSN=dsn.FormatDSN()
- c.DB,err=database.Open(ctx,cfg.Database);if err!=nil{return nil,err}
- if err=checker.Add(health.Probe{Name:"database",Timeout:cfg.Database.PingTimeout,Check:c.DB.Health});err!=nil{return nil,err}
- {{end}}
- {{if ne .Storage "none"}}if err=c.InitStorage(ctx,cfg.Storage);err!=nil{return nil,err}{{end}}
- return c,nil
-}
-
-// RequestShutdown reports a fatal dependency failure, or a normal stop when
-// err is nil. It returns immediately; generated main drains and cleans up.
-func(c *Context)RequestShutdown(err error){c.Lifecycle.RequestShutdown(err)}
+// Init is project-owned. Add dependencies here and immediately register each
+// cleanup with c.OnClose. Returning an error automatically rolls everything back.
+// Generated infrastructure is ready here. Never create another App or logger.
+func(c *Context)Init(ctx context.Context)error {return nil}
--- a/cmd/go-omni/scaffold/templates/api-databaseOptions.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/api-databaseOptions.go.tmpl
@@ -0,0 +1,5 @@
+package servicecontext
+import mysqladapter "git.yuntuo.hk/k2safe/go-omni/database/mysql"
+// DatabaseOptions supplies explicit driver settings or bounded startup checks.
+// Keep schema/version requirements in this project; do not open another pool.
+func(c *Context)DatabaseOptions()[]mysqladapter.Option{return nil}
--- a/cmd/go-omni/scaffold/templates/api-runtime.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/api-runtime.go.tmpl
@@ -0,0 +1,33 @@
+package servicecontext
+import (
+ "context"
+ "errors"
+ "git.yuntuo.hk/k2safe/go-omni/health"
+ "git.yuntuo.hk/k2safe/go-omni/lifecycle"
+ "git.yuntuo.hk/k2safe/go-omni/logx"
+ {{if eq .Database "mysql"}}mysqladapter "git.yuntuo.hk/k2safe/go-omni/database/mysql"{{end}}
+ "{{.Module}}/internal/settings"
+ "{{.Module}}/internal/middleware"
+)
+// New is generator-owned. Customize dependencies in ServiceContext.Init.
+func New(ctx context.Context,logger *logx.Logger,configs ...settings.Config)(result *Context,err error){
+ if ctx==nil{ctx=context.Background()}
+ if err=ctx.Err();err!=nil{return nil,errors.Join(err,lifecycle.Cause(ctx))}
+ if logger==nil{return nil,errors.New("service context requires a logger")}
+ if len(configs)>1{return nil,errors.New("expected at most one configuration")}
+ cfg:=settings.Default();if len(configs)==1{cfg=configs[0]}
+ if err=cfg.Validate();err!=nil{return nil,err}
+ checker,err:=health.New();if err!=nil{return nil,err}
+ c:=&Context{Config:cfg,Logger:logger,Health:checker,Middlewares:middleware.Defaults(),Runtime:lifecycle.NewRuntime(ctx)}
+ ctx=logx.WithLogger(c.Context(),logger)
+ defer func(){if p:=recover();p!=nil{_ = c.Close();panic(p)};if err!=nil{err=c.Finish(err)}}()
+ {{if eq .Database "mysql"}}
+ options:=append([]mysqladapter.Option{mysqladapter.WithLogger(logger)},c.DatabaseOptions()...)
+ c.DB,err=mysqladapter.Open(ctx,cfg.Database,options...);if err!=nil{return nil,err}
+ c.OnClose(c.DB.Close)
+ if err=checker.Add(health.Probe{Name:"database",Timeout:cfg.Database.Pool.PingTimeout,Check:c.DB.Health});err!=nil{return nil,err}
+ {{end}}
+ {{if ne .Storage "none"}}if err=c.InitStorage(ctx,cfg.Storage);err!=nil{return nil,err}{{end}}
+ if err=c.Init(ctx);err!=nil{return nil,err}
+ return c,nil
+}
--- a/cmd/go-omni/scaffold/templates/legacyV013/api-close.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/legacyV013/api-close.go.tmpl
@@ -0,0 +1,23 @@
+package servicecontext
+import "errors"
+// Close is idempotent, including startup failure and graceful shutdown.
+func(c *Context)Close()error{
+ if c==nil{return nil}
+ c.closeOnce.Do(func(){
+ if c.Lifecycle!=nil{c.Lifecycle.RequestShutdown(nil)}
+ c.closeMu.Lock();c.closed=true;cleanups:=c.cleanups;c.cleanups=nil;c.closeMu.Unlock()
+ for i:=len(cleanups)-1;i>=0;i--{c.closeErr=errors.Join(c.closeErr,cleanups[i]())}
+ {{if ne .Storage "none"}}if c.storageClose!=nil{c.closeErr=errors.Join(c.closeErr,c.storageClose())}{{end}}
+ {{if eq .Database "mysql"}}if c.DB!=nil{c.closeErr=errors.Join(c.closeErr,c.DB.Close())}{{end}}
+ })
+ return c.closeErr
+}
+
+// OnClose transfers a resource cleanup to this context immediately after creation.
+// Hooks run once in reverse order, also when later initialization fails.
+func(c *Context)OnClose(cleanup func()error) {
+ if cleanup==nil{return}
+ c.closeMu.Lock();defer c.closeMu.Unlock()
+ if c.closed{panic("svc: register cleanup after Close")}
+ c.cleanups=append(c.cleanups,cleanup)
+}
--- a/cmd/go-omni/scaffold/templates/legacyV013/api-context.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/legacyV013/api-context.go.tmpl
@@ -0,0 +1,68 @@
+package servicecontext
+import (
+ "context"
+ "errors"
+ "sync"
+ {{if ne .Storage "none"}}"net/http"
+ "git.yuntuo.hk/k2safe/go-omni/storage"{{end}}
+ {{if eq .Database "mysql"}}"time"
+ "git.yuntuo.hk/k2safe/go-omni/database"
+ "github.com/go-sql-driver/mysql"{{end}}
+ "git.yuntuo.hk/k2safe/go-omni/health"
+ "git.yuntuo.hk/k2safe/go-omni/httpx"
+ "git.yuntuo.hk/k2safe/go-omni/logx"
+ "git.yuntuo.hk/k2safe/go-omni/lifecycle"
+ "{{.Module}}/internal/settings"
+ "{{.Module}}/internal/middleware"
+)
+// Context owns infrastructure, while Logger is borrowed from main.
+// Add business repositories here; HTTP contracts do not define database tables.
+type Context struct {
+ Lifecycle *lifecycle.Controller
+ Config settings.Config
+ cleanups []func()error
+ Logger *logx.Logger
+ Health *health.Checker
+ Middlewares map[string]httpx.Middleware
+ {{if eq .Database "mysql"}}DB *database.DB{{end}}
+ {{if ne .Storage "none"}}
+ Files storage.Store
+ Uploads *storage.Uploader
+ Downloads storage.Presigner
+ UploadLinks storage.UploadPresigner
+ FileHTTP http.Handler
+ storageClose func()error
+ {{end}}
+ closeMu sync.Mutex
+ closed bool
+ closeOnce sync.Once
+ closeErr error
+}
+// Pass the settings loaded by main. The optional form supports lightweight
+// tests without infrastructure; selected adapters still require valid settings.
+func New(ctx context.Context,logger *logx.Logger,configs ...settings.Config)(result *Context,err error){
+ if ctx==nil{ctx=context.Background()}
+ if err=ctx.Err();err!=nil{return nil,errors.Join(err,lifecycle.Cause(ctx))}
+ if len(configs)>1{return nil,errors.New("expected at most one configuration")}
+ cfg:=settings.Default();if len(configs)==1{cfg=configs[0]}
+ _=cfg
+ checker,err:=health.New();if err!=nil{return nil,err}
+ c:=&Context{Config:cfg,Logger:logger,Health:checker,Middlewares:middleware.Defaults(),Lifecycle:lifecycle.New(ctx)}
+ ctx=c.Lifecycle.Context()
+ defer func(){if err!=nil{err=errors.Join(err,c.Close());if cause:=c.Lifecycle.Err();cause!=nil && !errors.Is(err,cause){err=errors.Join(err,cause)}}}()
+ {{if eq .Database "mysql"}}
+ if err=cfg.Validate();err!=nil{return nil,err}
+ dsn,parseErr:=mysql.ParseDSN(cfg.Database.DSN)
+ if parseErr!=nil || dsn.DBName=="" {return nil,errors.New("GO_OMNI_DB_DSN must contain a valid MySQL database name")}
+ dsn.ParseTime=true;dsn.Loc=time.UTC
+ cfg.Database.DSN=dsn.FormatDSN()
+ c.DB,err=database.Open(ctx,cfg.Database);if err!=nil{return nil,err}
+ if err=checker.Add(health.Probe{Name:"database",Timeout:cfg.Database.PingTimeout,Check:c.DB.Health});err!=nil{return nil,err}
+ {{end}}
+ {{if ne .Storage "none"}}if err=c.InitStorage(ctx,cfg.Storage);err!=nil{return nil,err}{{end}}
+ return c,nil
+}
+
+// RequestShutdown reports a fatal dependency failure, or a normal stop when
+// err is nil. It returns immediately; generated main drains and cleans up.
+func(c *Context)RequestShutdown(err error){c.Lifecycle.RequestShutdown(err)}
--- a/cmd/go-omni/scaffold/templates/legacyV013/api-options.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/legacyV013/api-options.go.tmpl
@@ -0,0 +1,11 @@
+package servicecontext
+import (
+ omni "git.yuntuo.hk/k2safe/go-omni"
+ "git.yuntuo.hk/k2safe/go-omni/httpx"
+)
+// AppOptions runs before routes are registered. Register project error catalogs
+// here with omni.WithErrors. It must not create resources or another App.
+func(c *Context)AppOptions()[]omni.Option{return nil}
+// GlobalMiddleware runs for all endpoints, including App 404/405 fallbacks.
+// Named route middleware lives in Middlewares and is selected by the API contract.
+func(c *Context)GlobalMiddleware()[]httpx.Middleware{return nil}
--- a/cmd/go-omni/scaffold/templates/legacyV013/modules-config.yaml.tmpl
+++ b/cmd/go-omni/scaffold/templates/legacyV013/modules-config.yaml.tmpl
@@ -0,0 +1,59 @@
+# Non-secret settings only. Environment variables override these values.
+server:
+  address: '127.0.0.1:8080'
+  enableLogger: true
+  slowRequestThreshold: 500ms
+  shutdownTimeout: 10s
+{{if .API}}  endpoints:
+    liveness:
+      enabled: true
+      path: /health/live
+      responseMode: app
+    readiness:
+      enabled: true
+      path: /health/ready
+      responseMode: app
+    openapi:
+      enabled: true
+      path: /openapi.json
+{{end}}
+  log:
+    service: {{printf "%q" .Module}}
+    level: info
+    format: {{.LogFormat}}
+{{if eq .LogOutput "file"}}    file: './var/log/server.log'
+    rotation:
+      enabled: true
+      maxSizeMb: 100
+      maxBackups: 10
+      maxAgeDays: 7
+      compress: true
+{{else}}    output: {{.LogOutput}}
+{{end}}    redactKeys: []
+{{if ne .Storage "none"}}storage:
+  provider: {{.Storage}}
+  maxBytes: 33554432
+  contentTypes: ['text/plain', 'image/png', 'image/jpeg', 'application/pdf']
+  linkTtl: 5m
+  requestTimeout: 30s
+{{if eq .Storage "local"}}  root: './var/files'
+  publicUrl: 'http://127.0.0.1:8080/storage/object'
+{{else}}  bucket: '' # set GO_OMNI_STORAGE_BUCKET
+  secure: true
+{{if eq .Storage "r2"}}  accountId: '' # set GO_OMNI_STORAGE_ACCOUNT_ID
+  region: auto
+{{else if eq .Storage "s3"}}  endpoint: '' # set GO_OMNI_STORAGE_ENDPOINT (host[:port])
+  region: us-east-1
+{{else}}  region: cn-hangzhou
+  endpoint: '' # empty uses the official regional endpoint
+{{end}}{{end}}{{end}}
+
+{{if and .API (eq .Database "mysql")}}database:
+  driver: mysql
+  maxOpenConns: 10
+  maxIdleConns: 5
+  connMaxLifetime: 30m
+  connMaxIdleTime: 5m
+  pingTimeout: 5s
+# GO_OMNI_DB_DSN supplies the secret connection string.
+{{end}}
--- a/cmd/go-omni/scaffold/templates/legacyV013/modules-settings.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/legacyV013/modules-settings.go.tmpl
@@ -0,0 +1,140 @@
+// Package settings owns this project's configuration; it adds no business identity model.
+package settings
+
+import (
+ "errors"
+ "os"
+ "strings"
+ "time"
+ {{if ne .Storage "none"}}"fmt"
+ {{if ne .Storage "r2"}}"net/url"{{else}}"regexp"{{end}}
+ "strconv"
+ "git.yuntuo.hk/k2safe/go-omni/storage"{{end}}
+ {{if and .API (eq .Database "mysql")}}"git.yuntuo.hk/k2safe/go-omni/database"{{end}}
+ "git.yuntuo.hk/k2safe/go-omni/config"
+ "git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+type Config struct {
+ Server config.Config `json:"server"`
+ {{if and .API (eq .Database "mysql")}}Database database.Config `json:"database"`{{end}}
+ {{if ne .Storage "none"}}Storage StorageConfig `json:"storage"`{{end}}
+}
+
+func Default() Config {
+ server:=config.Default()
+ server.Address="127.0.0.1:8080"
+ server.EnableLogger=true
+ server.SlowRequestThreshold=500*time.Millisecond
+ server.Log.Service={{printf "%q" .Module}}
+ server.Log.Format={{printf "%q" .LogFormat}}
+ {{if eq .LogOutput "file"}}server.Log.File="./var/log/server.log"
+ server.Log.Rotation=logx.RotationConfig{Enabled:true,MaxSizeMB:100,MaxBackups:10,MaxAgeDays:7,Compress:true}
+ {{else}}server.Log.Output={{printf "%q" .LogOutput}}{{end}}
+ return Config{Server:server{{if and .API (eq .Database "mysql")}},Database:database.DefaultConfig(){{end}}{{if ne .Storage "none"}},Storage:StorageConfig{
+  Provider:{{printf "%q" .Storage}}, Root:"./var/files", PublicURL:"http://127.0.0.1:8080/storage/object",
+  Secure:true, MaxBytes:32<<20, ContentTypes:[]string{"text/plain","image/png","image/jpeg","application/pdf"},
+  LinkTTL:5*time.Minute, RequestTimeout:30*time.Second,
+  {{if eq .Storage "s3"}}Region:"us-east-1",{{end}}
+  {{if eq .Storage "r2"}}Region:"auto",{{end}}
+  {{if eq .Storage "oss"}}Region:"cn-hangzhou",{{end}}
+ }{{end}}}
+}
+
+// Load uses defaults -> strict YAML/JSON -> nonempty environment variables.
+// Pass an empty path to use only defaults and environment.
+func Load(path string)(Config,error) {
+ cfg:=Default()
+ var err error
+ if path!="" { cfg,err=config.DecodeFile(path,cfg);if err!=nil{return Config{},err} }
+ cfg.Server,err=config.ApplyEnv(cfg.Server,"")
+ if err!=nil{return Config{},err}
+ // A stream explicitly selected by environment overrides a file profile.
+ if output:=strings.TrimSpace(os.Getenv("GO_OMNI_LOG_OUTPUT"));output!="" && strings.TrimSpace(os.Getenv("GO_OMNI_LOG_FILE"))=="" {
+  cfg.Server.Log.File="";cfg.Server.Log.Rotation=logx.RotationConfig{}
+ }
+ {{if ne .Storage "none"}}
+ if err=cfg.Storage.applyEnv();err!=nil{return Config{},err}
+ {{end}}
+ {{if and .API (eq .Database "mysql")}}cfg.Database,err=database.ApplyEnv(cfg.Database,"");if err!=nil{return Config{},err}{{end}}
+ if err=cfg.Validate();err!=nil{return Config{},err}
+ return cfg,nil
+}
+func (c Config) Validate()error {
+ {{if and .API (eq .Database "mysql")}}
+ if err:=c.Database.Validate();err!=nil{return err}
+ if c.Database.Driver!="mysql" || c.Database.MaxOpenConns<1 {return errors.New("database requires driver mysql and a positive maxOpenConns")}
+ {{end}}
+ if err:=c.Server.Validate();err!=nil{return err}
+ if c.Server.Log.Format!="json" && c.Server.Log.Format!="text" {return errors.New("log.format must be json or text")}
+ switch strings.ToLower(c.Server.Log.Level) {case "debug","info","warn","warning","error":default:return errors.New("invalid log.level")}
+ {{if ne .Storage "none"}}return c.Storage.Validate(){{else}}return nil{{end}}
+}
+
+{{if ne .Storage "none"}}
+type StorageConfig struct {
+ Provider string `json:"provider"`
+ Root string `json:"root"`
+ PublicURL string `json:"publicUrl"`
+ Endpoint string `json:"endpoint"`
+ Region string `json:"region"`
+ Bucket string `json:"bucket"`
+ AccountID string `json:"accountId"`
+ Secure bool `json:"secure"`
+ MaxBytes int64 `json:"maxBytes"`
+ ContentTypes []string `json:"contentTypes"`
+ LinkTTL time.Duration `json:"linkTtl"`
+ RequestTimeout time.Duration `json:"requestTimeout"`
+ // Secrets are environment-only and cannot be populated by config files.
+ FilesToken string `json:"-"`
+ SigningKey string `json:"-"`
+ AccessKey string `json:"-"`
+ SecretKey string `json:"-"`
+ SessionToken string `json:"-"`
+}
+func (s StorageConfig) Policy()storage.UploadPolicy{return storage.UploadPolicy{MaxBytes:s.MaxBytes,ContentTypes:s.ContentTypes}}
+func (s *StorageConfig) applyEnv()error {
+ values:=map[string]*string{
+  "GO_OMNI_STORAGE_ROOT":&s.Root,"GO_OMNI_STORAGE_PUBLIC_URL":&s.PublicURL,
+  "GO_OMNI_STORAGE_ENDPOINT":&s.Endpoint,"GO_OMNI_STORAGE_REGION":&s.Region,
+  "GO_OMNI_STORAGE_BUCKET":&s.Bucket,"GO_OMNI_STORAGE_ACCOUNT_ID":&s.AccountID,
+  "GO_OMNI_STORAGE_SIGNING_KEY":&s.SigningKey,"GO_OMNI_FILES_TOKEN":&s.FilesToken,
+  "GO_OMNI_STORAGE_ACCESS_KEY":&s.AccessKey,"GO_OMNI_STORAGE_SECRET_KEY":&s.SecretKey,
+  "GO_OMNI_STORAGE_SESSION_TOKEN":&s.SessionToken,
+ }
+ for name,target:=range values {if value:=strings.TrimSpace(os.Getenv(name));value!=""{*target=value}}
+ for name,target:=range map[string]*time.Duration{"GO_OMNI_STORAGE_LINK_TTL":&s.LinkTTL,"GO_OMNI_STORAGE_REQUEST_TIMEOUT":&s.RequestTimeout} {
+  if value:=strings.TrimSpace(os.Getenv(name));value!="" {v,err:=time.ParseDuration(value);if err!=nil{return fmt.Errorf("%s must be a duration",name)};*target=v}
+ }
+ if value:=os.Getenv("GO_OMNI_STORAGE_MAX_BYTES");value!=""{v,err:=strconv.ParseInt(value,10,64);if err!=nil{return errors.New("GO_OMNI_STORAGE_MAX_BYTES must be an integer")};s.MaxBytes=v}
+ if value:=os.Getenv("GO_OMNI_STORAGE_SECURE");value!=""{v,err:=strconv.ParseBool(value);if err!=nil{return errors.New("GO_OMNI_STORAGE_SECURE must be a boolean")};s.Secure=v}
+ if value:=strings.TrimSpace(os.Getenv("GO_OMNI_STORAGE_CONTENT_TYPES"));value!="" {s.ContentTypes=strings.Split(value,",");for i:=range s.ContentTypes{s.ContentTypes[i]=strings.TrimSpace(s.ContentTypes[i])}}
+ return nil
+}
+func (s StorageConfig) Validate()error {
+ if s.Provider!={{printf "%q" .Storage}} {return errors.New("storage.provider must match the adapter selected at generation")}
+ if err:=s.Policy().Validate();err!=nil{return err}
+ if s.LinkTTL<time.Second || s.LinkTTL>time.Hour{return errors.New("storage.linkTtl must be 1s..1h")}
+ if s.RequestTimeout<=0 || s.RequestTimeout>5*time.Minute{return errors.New("storage.requestTimeout must be >0 and <=5m")}
+ {{if not .API}}if len(s.FilesToken)<32 || strings.ContainsAny(s.FilesToken," \t\r\n") {return errors.New("set GO_OMNI_FILES_TOKEN to a token of at least 32 bytes without whitespace")}{{end}}
+ {{if eq .Storage "local"}}
+ if s.Root=="" {return errors.New("storage.root is required")}
+ u,err:=url.Parse(s.PublicURL)
+ if err!=nil || u.Host=="" || u.Hostname()=="" || (u.Scheme!="http" && u.Scheme!="https") || u.User!=nil || u.RawQuery!="" || u.Fragment!="" || u.Path!="/storage/object" {return errors.New("storage.publicUrl must be an absolute HTTP(S) URL ending in /storage/object")}
+ if len(s.SigningKey)<32 {return errors.New("set GO_OMNI_STORAGE_SIGNING_KEY to a stable secret of at least 32 bytes")}
+ {{else}}
+ if s.Bucket=="" || s.Region=="" || s.AccessKey=="" || s.SecretKey=="" {return errors.New("storage bucket, region and GO_OMNI_STORAGE_ACCESS_KEY/SECRET_KEY are required")}
+ {{if eq .Storage "r2"}}
+ if !regexp.MustCompile(`^[a-fA-F0-9]{32}$`).MatchString(s.AccountID) || s.Region!="auto" || !s.Secure {return errors.New("R2 requires a 32-hex accountId, region auto and secure=true")}
+ if s.Endpoint!=""{return errors.New("this R2 profile derives endpoint from accountId; customize servicecontext for a jurisdiction-specific endpoint")}
+ {{else if eq .Storage "s3"}}
+ u,err:=url.Parse("https://"+s.Endpoint)
+ if err!=nil || s.Endpoint=="" || u.Hostname()=="" || u.User!=nil || u.Path!="" || u.RawQuery!="" || u.Fragment!="" {return errors.New("S3 endpoint must be host[:port] without scheme or path")}
+ {{else if eq .Storage "oss"}}
+ if s.Endpoint!="" {u,err:=url.Parse(s.Endpoint);if err!=nil || u.Scheme!="https" || u.Hostname()=="" || u.User!=nil || u.Path!="" || u.RawQuery!="" || u.Fragment!="" {return errors.New("OSS endpoint must be an HTTPS origin")}}
+ if !s.Secure{return errors.New("OSS requires secure=true")}
+ {{end}}
+ {{end}}
+ return nil
+}
+{{end}}
--- a/cmd/go-omni/scaffold/templates/legacyV013/modules-storage.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/legacyV013/modules-storage.go.tmpl
@@ -0,0 +1,79 @@
+package servicecontext
+
+import (
+ "context"
+ "errors"
+ {{if eq .Storage "local"}}
+ "git.yuntuo.hk/k2safe/go-omni/storage/local"
+ {{else}}
+ "net"
+ "net/http"
+ "time"
+ {{if eq .Storage "oss"}}
+ ossStore "git.yuntuo.hk/k2safe/go-omni/storage/oss"
+ ossSDK "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
+ "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
+ {{else}}
+ "git.yuntuo.hk/k2safe/go-omni/storage/s3"
+ "github.com/minio/minio-go/v7/pkg/credentials"
+ {{end}}{{end}}
+ "git.yuntuo.hk/k2safe/go-omni/storage"
+ "{{.Module}}/internal/settings"
+)
+
+// InitStorage is called once, before serving requests. The composition root
+// owns provider clients; business services receive only capability interfaces.
+func (c *Context) InitStorage(ctx context.Context,cfg settings.StorageConfig)error {
+ if c==nil || ctx==nil{return errors.New("storage initialization requires context")}
+ c.closeMu.Lock();defer c.closeMu.Unlock()
+ if c.closed{return errors.New("service dependencies are closed")}
+ if err:=ctx.Err();err!=nil{return err}
+ if c.Files!=nil{return errors.New("storage already initialized")}
+ if err:=cfg.Validate();err!=nil{return err}
+ {{if eq .Storage "local"}}
+ files,err:=local.New(cfg.Root,cfg.MaxBytes)
+ if err!=nil{return err}
+ signer,err:=storage.NewUploadSigner(files,cfg.PublicURL,[]byte(cfg.SigningKey),cfg.Policy())
+ if err!=nil{return err}
+ uploader,err:=storage.NewUploader(files,cfg.Policy())
+ if err!=nil{return err}
+ c.Files,c.Uploads,c.Downloads,c.UploadLinks,c.FileHTTP=files,uploader,signer,signer,signer
+ {{else}}
+ // Dedicated bounded pool, never the process-wide default transport.
+ transport:=&http.Transport{
+  Proxy:http.ProxyFromEnvironment,
+  DialContext:(&net.Dialer{Timeout:5*time.Second,KeepAlive:30*time.Second}).DialContext,
+  ForceAttemptHTTP2:true, MaxIdleConns:32,MaxIdleConnsPerHost:8,MaxConnsPerHost:32,
+  IdleConnTimeout:90*time.Second,TLSHandshakeTimeout:5*time.Second,
+  ResponseHeaderTimeout:cfg.RequestTimeout,
+ }
+ initialized:=false
+ defer func(){if !initialized{transport.CloseIdleConnections()}}()
+ {{if eq .Storage "oss"}}
+ sdkConfig:=ossSDK.LoadDefaultConfig().WithRegion(cfg.Region).
+  WithSignatureVersion(ossSDK.SignatureVersionV4).
+  WithAdditionalHeaders([]string{"content-length"}).
+  WithCredentialsProvider(credentials.NewStaticCredentialsProvider(cfg.AccessKey,cfg.SecretKey,cfg.SessionToken)).
+  WithHttpClient(&http.Client{Transport:transport,Timeout:cfg.RequestTimeout})
+ if cfg.Endpoint!=""{sdkConfig.WithEndpoint(cfg.Endpoint)}
+ files,err:=ossStore.New(ossSDK.NewClient(sdkConfig),cfg.Bucket,cfg.MaxBytes)
+ {{else}}
+ creds:=credentials.NewStaticV4(cfg.AccessKey,cfg.SecretKey,cfg.SessionToken)
+ {{if eq .Storage "r2"}}
+ options,err:=s3.R2Config(cfg.AccountID,cfg.Bucket,creds)
+ if err!=nil{return err}
+ options.MaxBytes,options.Transport=cfg.MaxBytes,transport
+ {{else}}
+ options:=s3.Config{Endpoint:cfg.Endpoint,Region:cfg.Region,Bucket:cfg.Bucket,Secure:cfg.Secure,MaxBytes:cfg.MaxBytes,Credentials:creds,Transport:transport}
+ {{end}}
+ files,err:=s3.Open(options)
+ {{end}}
+ if err!=nil{return err}
+ uploader,err:=storage.NewUploader(files,cfg.Policy())
+ if err!=nil{return err}
+ c.Files,c.Uploads,c.Downloads,c.UploadLinks=files,uploader,files,uploader
+ c.storageClose=func()error{transport.CloseIdleConnections();return nil}
+ initialized=true
+ {{end}}
+ return nil
+}
--- a/cmd/go-omni/scaffold/templates/modules-config.yaml.tmpl
+++ b/cmd/go-omni/scaffold/templates/modules-config.yaml.tmpl
@@ -49,11 +49,16 @@ server:
 {{end}}{{end}}{{end}}

 {{if and .API (eq .Database "mysql")}}database:
-  driver: mysql
-  maxOpenConns: 10
-  maxIdleConns: 5
-  connMaxLifetime: 30m
-  connMaxIdleTime: 5m
-  pingTimeout: 5s
-# GO_OMNI_DB_DSN supplies the secret connection string.
+  host: 127.0.0.1
+  port: 3306
+  database: '' # GO_OMNI_DB_DATABASE
+  user: '' # GO_OMNI_DB_USER; password via GO_OMNI_DB_PASSWORD
+  tls:
+    mode: required
+  pool:
+    maxOpenConns: 10
+    maxIdleConns: 5
+    connMaxLifetime: 30m
+    connMaxIdleTime: 5m
+    pingTimeout: 5s
 {{end}}
--- a/cmd/go-omni/scaffold/templates/modules-storage.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/modules-storage.go.tmpl
@@ -25,8 +25,8 @@ import (
 // owns provider clients; business services receive only capability interfaces.
 func (c *Context) InitStorage(ctx context.Context,cfg settings.StorageConfig)error {
 if c==nil || ctx==nil{return errors.New("storage initialization requires context")}
- c.closeMu.Lock();defer c.closeMu.Unlock()
- if c.closed{return errors.New("service dependencies are closed")}
+ {{if .API}}if c.Runtime==nil || c.Context().Err()!=nil{return errors.New("service dependencies are closed")}{{else}}c.closeMu.Lock();defer c.closeMu.Unlock()
+ if c.closed{return errors.New("service dependencies are closed")}{{end}}
 if err:=ctx.Err();err!=nil{return err}
 if c.Files!=nil{return errors.New("storage already initialized")}
 if err:=cfg.Validate();err!=nil{return err}
@@ -72,7 +72,7 @@ func (c *Context) InitStorage(ctx context.Context,cfg settings.StorageConfig)err
 uploader,err:=storage.NewUploader(files,cfg.Policy())
 if err!=nil{return err}
 c.Files,c.Uploads,c.Downloads,c.UploadLinks=files,uploader,files,uploader
- c.storageClose=func()error{transport.CloseIdleConnections();return nil}
+ {{if .API}}c.OnClose(func()error{transport.CloseIdleConnections();return nil}){{else}}c.storageClose=func()error{transport.CloseIdleConnections();return nil}{{end}}
 initialized=true
 {{end}}
 return nil
--- a/cmd/go-omni/scaffold/version.go
+++ b/cmd/go-omni/scaffold/version.go
@@ -10,7 +10,7 @@ const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"
 // Source builds can carry an unpublished VCS version (including +dirty).
 // Keep this fallback in sync with the next release; installed CLIs use their
 // downloaded module version, which also has a module checksum.
-const defaultFrameworkVersion = "v0.13.0-preview"
+const defaultFrameworkVersion = "v0.14.0-preview"

 // This target is not a claim that the release already exists. Source users
 // select a local framework checkout until the module templates are published.
--- a/cmd/go-omni/upgrade.go
+++ b/cmd/go-omni/upgrade.go
@@ -0,0 +1,44 @@
+package main
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"git.yuntuo.hk/k2safe/go-omni/cmd/go-omni/apigen"
+	"io"
+)
+
+func runUpgrade(args []string) error {
+	flags := flag.NewFlagSet("upgrade", flag.ContinueOnError)
+	flags.SetOutput(io.Discard)
+	dir := flags.String("dir", ".", "service directory")
+	apply := flags.Bool("apply", false, "apply only recognized baseline changes")
+	preview := flags.String("preview", "", "write proposed infrastructure into an empty directory")
+	dry := flags.Bool("dry-run", false, "show the upgrade plan")
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+	if flags.NArg() != 0 {
+		return errors.New("unexpected upgrade argument")
+	}
+	if *apply && (*preview != "" || *dry) {
+		return errors.New("--apply cannot be combined with preview/dry-run")
+	}
+	var plan apigen.UpgradePlan
+	var err error
+	if *apply {
+		plan, err = apigen.ApplyUpgrade(*dir)
+	} else if *preview != "" {
+		plan, err = apigen.PreviewUpgrade(*dir, *preview)
+	} else {
+		plan, err = apigen.PlanUpgrade(*dir)
+	}
+	for _, c := range plan.Changes {
+		kind := "safe"
+		if c.Manual {
+			kind = "review"
+		}
+		fmt.Printf("%-6s %-6s %s\n", kind, c.Action, c.Path)
+	}
+	return err
+}
--- a/cmd/go-omni/workspace.go
+++ b/cmd/go-omni/workspace.go
@@ -0,0 +1,25 @@
+package main
+
+import (
+	"errors"
+	"flag"
+	"git.yuntuo.hk/k2safe/go-omni/cmd/go-omni/apigen"
+	"io"
+	"os"
+)
+
+func runWorkspace(args []string) error {
+	if len(args) < 1 {
+		return errors.New("usage: go-omni workspace <format|generate|check> --file omni.workspace.json")
+	}
+	flags := flag.NewFlagSet("workspace", flag.ContinueOnError)
+	flags.SetOutput(io.Discard)
+	path := flags.String("file", "omni.workspace.json", "workspace configuration")
+	if err := flags.Parse(args[1:]); err != nil {
+		return err
+	}
+	if flags.NArg() != 0 {
+		return errors.New("unexpected workspace argument")
+	}
+	return apigen.Workspace(*path, args[0], os.Stdout)
+}