feat(web): PropertyDefinition editor, form-help, and per-item help

internal/module/evolution/schema/foreignkey.go

@@ -98,8 +98,11 @@ func (m *foreignKeyMigrator) getManyToOneKeys() ([]ForeignKeyInfo, error) {
 					continue
 				}
 
-				// Treat fields with a select clause as virtual and skip FK creation.
-				if _, hasSelect := opts["select"]; hasSelect {
+				skip, skipErr := shouldSkipManyToOneForeignKey(field, opts)
+				if skipErr != nil {
+					return nil, skipErr
+				}
+				if skip {
 					continue
 				}
 
@@ -139,6 +142,51 @@ func (m *foreignKeyMigrator) getManyToOneKeys() ([]ForeignKeyInfo, error) {
 	return foreignKeys, nil
 }
 
+// shouldSkipManyToOneForeignKey skips virtual / non-column ManyToOne fields.
+// Prefer ResolvedSpec.Migration.ShouldCreateColumn (COMPUTE_STORE_FALSE, related,
+// sqlCompute, …); also skip @Field({ select }) and bare @Compute({ store: false })
+// when ResolvedSpec is absent.
+func shouldSkipManyToOneForeignKey(field *meta.Field, opts map[string]interface{}) (bool, error) {
+	if _, hasSelect := opts["select"]; hasSelect {
+		return true, nil
+	}
+	if field == nil {
+		return false, nil
+	}
+	resolved, err := field.GetResolvedSpec()
+	if err != nil {
+		return false, fmt.Errorf("error unmarshal field resolved spec for %s: %w", field.Name, err)
+	}
+	if resolved != nil {
+		return !resolved.Migration.ShouldCreateColumn, nil
+	}
+	return fieldHasNonStoredComputeDecorator(field), nil
+}
+
+func fieldHasNonStoredComputeDecorator(field *meta.Field) bool {
+	if field == nil {
+		return false
+	}
+	for _, decorator := range field.Decorators {
+		if decorator == nil || decorator.Name != "Compute" {
+			continue
+		}
+		for _, arg := range decorator.Arguments {
+			if arg == nil || arg.Type != "ObjectLiteral" || arg.Value == "" {
+				continue
+			}
+			var computeOpts map[string]interface{}
+			if err := json.Unmarshal([]byte(arg.Value), &computeOpts); err != nil {
+				continue
+			}
+			if store, ok := computeOpts["store"].(bool); ok && !store {
+				return true
+			}
+		}
+	}
+	return false
+}
+
 func (m *foreignKeyMigrator) resolveTargetModelByPath(targetModelPath string) (*meta.Model, error) {
 	for _, model := range m.models {
 		if model != nil && model.Path == targetModelPath {
@@ -235,7 +283,14 @@ func (m *foreignKeyMigrator) createForeignKeys(foreignKeys []ForeignKeyInfo) err
 		// Create the new foreign key.
 		createSQL := builder.BuildForeignKeySQL(fk)
 		if err := db.Exec(createSQL).Error; err != nil {
-			return fmt.Errorf("create foreign key failed: %v", err)
+			return fmt.Errorf(
+				"create foreign key failed: table=%s column=%s refer=%s.%s: %w",
+				fk.TableName,
+				fk.ColumnName,
+				fk.ReferTableName,
+				fk.ReferColumnName,
+				err,
+			)
 		}
 	}
 

internal/module/evolution/schema/foreignkey_test.go

@@ -250,11 +250,285 @@ func TestForeignKeyMigratorRuntimePaths(t *testing.T) {
 		fkMigrator := newForeignKeyMigrator(runtimeScope, nil, nil).(*foreignKeyMigrator)
 		fks := []ForeignKeyInfo{{TableName: "sales_order", ColumnName: "owner_id", ReferTableName: "sales_user", ReferColumnName: "id", OnDelete: "CASCADE"}}
 
-		if err := fkMigrator.createForeignKeys(fks); err == nil || !strings.Contains(err.Error(), "create foreign key failed") {
+		err := fkMigrator.createForeignKeys(fks)
+		if err == nil || !strings.Contains(err.Error(), "create foreign key failed") {
 			t.Fatalf("expected create foreign key error, got %v", err)
 		}
+		for _, want := range []string{
+			"table=sales_order",
+			"column=owner_id",
+			"refer=sales_user.id",
+		} {
+			if !strings.Contains(err.Error(), want) {
+				t.Fatalf("expected %q in error, got %v", want, err)
+			}
+		}
 		if err := fkMigrator.MigrateForeignKeys(); err != nil {
 			t.Fatalf("MigrateForeignKeys() with no keys error = %v", err)
 		}
 	})
+
+	t.Run("skips non-stored compute many-to-one via ResolvedSpec", func(t *testing.T) {
+		runtimeScope := newSchemaTestScope(t)
+		target := &meta.Model{Name: "Line", Path: "sandbox/line.ts", ModelTable: "sandbox_line"}
+		stored := newRelationField("OwnerId", "sandbox/line", `{"type":"ManyToOne"}`)
+		virtual := newRelationField("PrimaryLineId", "sandbox/line", `{"type":"ManyToOne","index":true,"readonly":true}`)
+		if err := virtual.SetResolvedSpec(&meta.FieldResolvedSpec{
+			FieldName: "PrimaryLineId",
+			Structural: meta.FieldStructuralSpec{
+				Name:      "PrimaryLineId",
+				FieldType: "ManyToOne",
+			},
+			Migration: meta.FieldMigrationDecision{
+				StorageKind:        "virtualRuntime",
+				ShouldCreateColumn: false,
+				ReasonCode:         "COMPUTE_STORE_FALSE",
+			},
+		}); err != nil {
+			t.Fatalf("SetResolvedSpec: %v", err)
+		}
+		source := &meta.Model{
+			Name:       "Record",
+			Path:       "sandbox/record.ts",
+			ModelTable: "sandbox_record",
+			Fields:     []*meta.Field{stored, virtual},
+		}
+
+		keys, err := newForeignKeyMigrator(runtimeScope, nil, []*meta.Model{source, target}).(*foreignKeyMigrator).getManyToOneKeys()
+		if err != nil {
+			t.Fatalf("getManyToOneKeys() error = %v", err)
+		}
+		if len(keys) != 1 || keys[0].ColumnName != "owner_id" {
+			t.Fatalf("expected only stored owner_id FK, got %#v", keys)
+		}
+	})
+
+	t.Run("skips non-stored compute many-to-one via Compute decorator fallback", func(t *testing.T) {
+		runtimeScope := newSchemaTestScope(t)
+		target := &meta.Model{Name: "Line", Path: "sandbox/line.ts", ModelTable: "sandbox_line"}
+		virtual := &meta.Field{
+			Name:           "PrimaryLineId",
+			ModuleSpecPath: "sandbox/line",
+			Decorators: []*meta.Decorator{
+				{
+					Name:      "Field",
+					Arguments: []*meta.Argument{{Type: "ObjectLiteral", Value: `{"type":"ManyToOne"}`}},
+				},
+				{
+					Name: "Compute",
+					Arguments: []*meta.Argument{
+						{Type: "StringLiteral", Value: "PrimaryLineId"},
+						{Type: "ObjectLiteral", Value: `{"deps":["Lines.Id"],"store":false}`},
+					},
+				},
+			},
+		}
+		source := &meta.Model{
+			Name:       "Record",
+			Path:       "sandbox/record.ts",
+			ModelTable: "sandbox_record",
+			Fields:     []*meta.Field{virtual},
+		}
+
+		keys, err := newForeignKeyMigrator(runtimeScope, nil, []*meta.Model{source, target}).(*foreignKeyMigrator).getManyToOneKeys()
+		if err != nil {
+			t.Fatalf("getManyToOneKeys() error = %v", err)
+		}
+		if len(keys) != 0 {
+			t.Fatalf("expected no FK for store:false Compute, got %#v", keys)
+		}
+	})
+}
+
+func TestShouldSkipManyToOneForeignKey(t *testing.T) {
+	t.Parallel()
+
+	t.Run("select option skips without consulting field", func(t *testing.T) {
+		skip, err := shouldSkipManyToOneForeignKey(nil, map[string]interface{}{"select": "expr"})
+		if err != nil || !skip {
+			t.Fatalf("expected skip for select, got skip=%v err=%v", skip, err)
+		}
+	})
+
+	t.Run("nil field without select does not skip", func(t *testing.T) {
+		skip, err := shouldSkipManyToOneForeignKey(nil, map[string]interface{}{})
+		if err != nil || skip {
+			t.Fatalf("expected no skip for nil field, got skip=%v err=%v", skip, err)
+		}
+	})
+
+	t.Run("GetResolvedSpec error wraps field name", func(t *testing.T) {
+		field := &meta.Field{Name: "OwnerId", ResolvedSpec: `{not-json`}
+		_, err := shouldSkipManyToOneForeignKey(field, map[string]interface{}{})
+		if err == nil || !strings.Contains(err.Error(), "error unmarshal field resolved spec for OwnerId") {
+			t.Fatalf("expected resolved-spec unwrap error, got %v", err)
+		}
+	})
+
+	t.Run("getManyToOneKeys propagates shouldSkip ResolvedSpec errors", func(t *testing.T) {
+		runtimeScope := newSchemaTestScope(t)
+		target := &meta.Model{Name: "Line", Path: "sandbox/line.ts", ModelTable: "sandbox_line"}
+		bad := &meta.Field{
+			Name:           "OwnerId",
+			ModuleSpecPath: "sandbox/line",
+			ResolvedSpec:   `{not-json`,
+			Decorators: []*meta.Decorator{
+				{Name: "Field", Arguments: []*meta.Argument{{Type: "ObjectLiteral", Value: `{"type":"ManyToOne"}`}}},
+			},
+		}
+		source := &meta.Model{
+			Name:       "Record",
+			Path:       "sandbox/record.ts",
+			ModelTable: "sandbox_record",
+			Fields:     []*meta.Field{bad},
+		}
+		_, err := newForeignKeyMigrator(runtimeScope, nil, []*meta.Model{source, target}).(*foreignKeyMigrator).getManyToOneKeys()
+		if err == nil || !strings.Contains(err.Error(), "error unmarshal field resolved spec for OwnerId") {
+			t.Fatalf("expected getManyToOneKeys to propagate skipErr, got %v", err)
+		}
+	})
+
+	t.Run("ResolvedSpec ShouldCreateColumn true/false", func(t *testing.T) {
+		stored := &meta.Field{Name: "OwnerId"}
+		if err := stored.SetResolvedSpec(&meta.FieldResolvedSpec{
+			FieldName: "OwnerId",
+			Migration: meta.FieldMigrationDecision{ShouldCreateColumn: true},
+		}); err != nil {
+			t.Fatalf("SetResolvedSpec: %v", err)
+		}
+		skip, err := shouldSkipManyToOneForeignKey(stored, nil)
+		if err != nil || skip {
+			t.Fatalf("expected keep stored column FK, got skip=%v err=%v", skip, err)
+		}
+
+		virtual := &meta.Field{Name: "PrimaryLineId"}
+		if err := virtual.SetResolvedSpec(&meta.FieldResolvedSpec{
+			FieldName: "PrimaryLineId",
+			Migration: meta.FieldMigrationDecision{ShouldCreateColumn: false, ReasonCode: "COMPUTE_STORE_FALSE"},
+		}); err != nil {
+			t.Fatalf("SetResolvedSpec: %v", err)
+		}
+		skip, err = shouldSkipManyToOneForeignKey(virtual, nil)
+		if err != nil || !skip {
+			t.Fatalf("expected skip virtual column, got skip=%v err=%v", skip, err)
+		}
+	})
+
+	t.Run("falls back to Compute decorator when ResolvedSpec absent", func(t *testing.T) {
+		virtual := &meta.Field{
+			Name: "PrimaryLineId",
+			Decorators: []*meta.Decorator{{
+				Name: "Compute",
+				Arguments: []*meta.Argument{
+					{Type: "ObjectLiteral", Value: `{"store":false}`},
+				},
+			}},
+		}
+		skip, err := shouldSkipManyToOneForeignKey(virtual, map[string]interface{}{})
+		if err != nil || !skip {
+			t.Fatalf("expected skip via Compute store:false, got skip=%v err=%v", skip, err)
+		}
+	})
+}
+
+func TestFieldHasNonStoredComputeDecorator(t *testing.T) {
+	t.Parallel()
+
+	if fieldHasNonStoredComputeDecorator(nil) {
+		t.Fatal("nil field must be false")
+	}
+
+	cases := []struct {
+		name  string
+		field *meta.Field
+		want  bool
+	}{
+		{
+			name:  "empty decorators",
+			field: &meta.Field{Name: "X"},
+			want:  false,
+		},
+		{
+			name: "nil decorator skipped",
+			field: &meta.Field{
+				Name:       "X",
+				Decorators: []*meta.Decorator{nil},
+			},
+			want: false,
+		},
+		{
+			name: "non-Compute decorator ignored",
+			field: &meta.Field{
+				Name: "X",
+				Decorators: []*meta.Decorator{{
+					Name:      "Field",
+					Arguments: []*meta.Argument{{Type: "ObjectLiteral", Value: `{"store":false}`}},
+				}},
+			},
+			want: false,
+		},
+		{
+			name: "Compute store true does not skip",
+			field: &meta.Field{
+				Name: "X",
+				Decorators: []*meta.Decorator{{
+					Name: "Compute",
+					Arguments: []*meta.Argument{
+						{Type: "ObjectLiteral", Value: `{"store":true}`},
+					},
+				}},
+			},
+			want: false,
+		},
+		{
+			name: "Compute store false skips",
+			field: &meta.Field{
+				Name: "X",
+				Decorators: []*meta.Decorator{{
+					Name: "Compute",
+					Arguments: []*meta.Argument{
+						{Type: "StringLiteral", Value: "fn"},
+						{Type: "ObjectLiteral", Value: `{"deps":["A"],"store":false}`},
+					},
+				}},
+			},
+			want: true,
+		},
+		{
+			name: "invalid Compute JSON ignored",
+			field: &meta.Field{
+				Name: "X",
+				Decorators: []*meta.Decorator{{
+					Name: "Compute",
+					Arguments: []*meta.Argument{
+						{Type: "ObjectLiteral", Value: `{bad`},
+					},
+				}},
+			},
+			want: false,
+		},
+		{
+			name: "empty ObjectLiteral value ignored",
+			field: &meta.Field{
+				Name: "X",
+				Decorators: []*meta.Decorator{{
+					Name: "Compute",
+					Arguments: []*meta.Argument{
+						nil,
+						{Type: "ObjectLiteral", Value: ""},
+						{Type: "StringLiteral", Value: `{"store":false}`},
+					},
+				}},
+			},
+			want: false,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := fieldHasNonStoredComputeDecorator(tc.field); got != tc.want {
+				t.Fatalf("got %v, want %v", got, tc.want)
+			}
+		})
+	}
 }

internal/module/lifecycle/install_tx_timing.go

@@ -11,7 +11,7 @@ import (
 
 // LogModuleCommitTxHold records how long a per-module Commit Required
 // transaction was held (install / upgrade / uninstall). Successful holds stay
-// Debug (ops metric); failures stay Info.
+// Debug (ops metric); failures log at Error.
 func LogModuleCommitTxHold(logger *slog.Logger, op string, caller string, started time.Time, err error) {
 	if logger == nil || started.IsZero() {
 		return
@@ -36,13 +36,14 @@ func logModuleCommitTxHold(logger *slog.Logger, op string, caller string, durati
 		"caller", caller,
 		"duration_ms", duration.Milliseconds(),
 	}
-	msg := op + " commit transaction hold completed"
 	if err != nil {
-		attrs = append(attrs, "error", err.Error())
-		logger.Info(msg, attrs...)
+		// Pass the error value (not err.Error()) so console/devslog/json
+		// ReplaceAttr can expand xfmt / QuickJS frames into a stack trace.
+		attrs = append(attrs, "error", err)
+		logger.Error(op+" commit transaction hold failed", attrs...)
 		return
 	}
-	logger.Debug(msg, attrs...)
+	logger.Debug(op+" commit transaction hold completed", attrs...)
 }
 
 // LogInstallOuterTxHold records install Commit / legacy outer Required hold time.